Campaign Settings Reference

Campaign settings define what a valid receipt looks like for your campaign. You create them once per campaignId with the Create Campaign Settings endpoint, then every receipt submitted against that campaign is checked against these rules.

Endpoint: POST https://api.taggun.io/api/validation/v1/campaign/settings/create/{campaignId}

Availability

📘

Availability: Receipt validation is included on the Advanced plan and above. Enable Campaign Validation in your account Feature Settings when it is available on your plan. See Plans & Feature Access and Setting Up Validation Campaigns.

Path Parameters

Request Body

All request body sections are optional, but a campaign with no validation sections will not perform useful validation. Include only the sections you want Taggun to evaluate.

📘

merchantNames, productCodes, productLineItems, balanceOwing, and fraudDetection support a section-level skip flag. smartValidate uses prompts[].skip. The date section has no skip field. When a supported skip value is true, data can still be returned, but the check is not added to passedValidations or failedValidations.

date

merchantNames

Accept or reject receipts based on the detected merchant. Pairs well with Merchant Intelligence name standardisation.

Do not combine list fields unless your confirmed campaign contract defines their interaction.

productCodes

Use product code rules when eligibility depends on SKUs, barcodes, serial-like identifiers, or other product code evidence on the receipt.

productCodes.description supplies a natural-language instruction; productCodes.list supplies exact accepted codes. The public contract does not currently define their evaluation order when both are supplied. Use one at a time unless API Engineering confirms the combined behavior for your integration.

productLineItems

Use line item rules when validation depends on the item name, quantity, or total price.

balanceOwing

Reject receipts that still show an amount owing — for example, lay-by or partially paid orders.

fraudDetection

Enable fraud-related validation checks for the campaign. For how each check works, see the Fraud Detection Suite.

Duplicate and similarity checks compare against eligible stored receipts. See Duplicate & Similarity Detection for matching behaviour and Security, Privacy & Data Residency for storage and retention.

smartValidate

SmartValidate is a current prompt-based Campaign Validation rule type for one narrow, receipt-visible yes/no criterion that the structured sections do not cover. Use the structured fields above when they directly represent the requirement. For positioning, boundaries, and the approved generic credit-card-payment illustration, see SmartValidate.

Worked Example

Create settings for a June campaign that accepts Fresh Market receipts for qualifying coffee products, requires nothing owing, runs duplicate checks, and includes one generic SmartValidate prompt:

curl --request POST \
     --url https://api.taggun.io/api/validation/v1/campaign/settings/create/coffee-june-2026 \
     --header 'accept: application/json' \
     --header 'apikey: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '
{
  "date": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-06-30T23:59:59.999Z"
  },
  "merchantNames": {
    "allowList": ["Fresh Market"]
  },
  "productCodes": {
    "list": ["COF-250", "COF-500"]
  },
  "productLineItems": {
    "names": ["Coffee Beans"],
    "quantity": { "min": 1, "max": 5 },
    "totalPrice": { "min": 5, "max": 80 }
  },
  "balanceOwing": { "max": 0.01 },
  "fraudDetection": { "allowSimilarityCheck": true },
  "smartValidate": {
    "prompts": [
      {
        "question": "Does this receipt show payment by credit card?",
        "example": { "is_credit_card": true },
        "skip": false
      }
    ]
  }
}
'

Request breakdown:

• date — receipts must be dated within June 2026.
• merchantNames — receipts matching the configured Fresh Market allow list qualify under this rule.
• productCodes — receipts must contain one of the exact accepted codes COF-250 or COF-500.
• productLineItems — a line item must match "Coffee Beans", with quantity 1–5 and total price 5–80.
• balanceOwing — the detected balance owing must not exceed 0.01. A value greater than zero is used because the current runtime does not perform the comparison when max is 0.
• fraudDetection — duplicate and similarity checking is on.
• smartValidate — adds the generic is_credit_card yes/no check. This illustrates the request shape; it does not describe a particular customer's production use case.

Response

Successful creation returns HTTP 201:

{
  "result": "Successfully created campaign settings",
  "statusCode": 201
}

Status codes

For general error handling, see Error Handling & Status Codes.

Key Notes

• campaignId is yours to choose (max 50 characters) — use a stable, descriptive ID like coffee-june-2026.
• To change rules after creation, use Update Campaign Settings — the update replaces the stored settings, so include every section that should remain active.
• Next step: submit receipts with Validating Receipts.

Need something not covered here? Contact [email protected] — see Contacting Support.