Create Campaign Settings

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

Access

Campaign settings require Campaign Validation access. See Setting Up Purchase Validation Campaigns.

Path Parameters

Field	Type	Description	Required
`campaignId`	string	The ID of the campaign to create settings for. Maximum 50 characters.	Yes

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.

Field	Type	Description
`date`	object	Optional receipt date window. If supplied, both `date.start` and `date.end` are required.
`merchantNames`	object	Optional merchant name allow and block rules.
`productCodes`	object	Optional product code extraction and validation rules.
`productLineItems`	object	Optional product line item matching rules.
`balanceOwing`	object	Optional maximum allowed balance owing.
`fraudDetection`	object	Optional duplicate, tamper, and digital receipt detection controls.
`smartValidate`	object	Optional custom true/false validation prompts.

`date`

Field	Type	Description	Required
`date.start`	string	Campaign start date in UTC ISO format, for example `2026-06-01T00:00:00.000Z`.	Yes, when `date` is supplied
`date.end`	string	Campaign end date in UTC ISO format, for example `2026-06-30T23:59:59.999Z`.	Yes, when `date` is supplied

`merchantNames`

Use merchant name rules to accept or reject receipts based on the detected merchant.

Field	Type	Description	Required
`merchantNames.skip`	boolean	When `true`, merchant data can still be returned but merchant name validation is not added to `passedValidations` or `failedValidations`. Defaults to `false`.	No
`merchantNames.returnFromTheList`	boolean	When `true`, Taggun returns the matched merchant from your supplied list when there is a match. Defaults to `false`.	No
`merchantNames.allowList`	string[]	Merchant names that are accepted for the campaign.	No
`merchantNames.blockList`	string[]	Merchant names that are rejected for the campaign.	No
`merchantNames.list`	string[]	Accepted merchant names. Prefer `allowList` for new integrations.	No

`productCodes`

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

productCodes.list is best when you already know the exact codes that are valid for the campaign. productCodes.description is useful when the code pattern or location is variable and you need Taggun to look for product-code evidence described in natural language.

If both description and list are supplied, Taggun uses the description to find candidate product codes and then checks those candidates against the list.

Field	Type	Description	Required
`productCodes.skip`	boolean	When `true`, product codes can still be returned but product code validation is not added to `passedValidations` or `failedValidations`. Defaults to `false`.	No
`productCodes.description`	string \| null	Natural-language instruction for finding relevant product codes, for example `Find product codes for Test Product`.	No
`productCodes.list`	string[]	Exact product codes accepted by the campaign.	No

`productLineItems`

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

Field	Type	Description	Required
`productLineItems.skip`	boolean	When `true`, line items can still be returned but line item validation is not added to `passedValidations` or `failedValidations`. Defaults to `false`.	No
`productLineItems.names`	string[]	Product names to match against receipt line items.	No
`productLineItems.totalPrice.min`	number	Minimum accepted line item total price.	Yes, when `totalPrice` is supplied
`productLineItems.totalPrice.max`	number	Maximum accepted line item total price.	Yes, when `totalPrice` is supplied
`productLineItems.quantity.min`	number	Minimum accepted line item quantity.	Yes, when `quantity` is supplied
`productLineItems.quantity.max`	number	Maximum accepted line item quantity.	Yes, when `quantity` is supplied
`productLineItems.shouldMatchAbbreviations`	boolean	When `true`, product name matching also considers abbreviations. Defaults to `false`.	No

`balanceOwing`

Field	Type	Description	Required
`balanceOwing.skip`	boolean	When `true`, balance owing can still be returned but balance owing validation is not added to `passedValidations` or `failedValidations`. Defaults to `false`.	No
`balanceOwing.max`	number	Maximum accepted amount owing on the receipt.	Yes, when `balanceOwing` is supplied

`fraudDetection`

Use these fields to enable fraud-related validation checks for a campaign. For more detail, see Fraud Detection and Prevention.

Field	Type	Description	Required
`fraudDetection.skip`	boolean	When `true`, fraud signals can still be returned but fraud validation checks are not added to `passedValidations` or `failedValidations`. Defaults to `false`.	No
`fraudDetection.allowSimilarityCheck`	boolean	Enables duplicate and similarity checks for submitted receipts.	No
`fraudDetection.allowTamperDetection`	boolean	Enables tamper detection checks.	No
`fraudDetection.allowDigitalDetection`	boolean	Enables digital receipt detection output.	No

`smartValidate`

Smart Validate prompts let you ask custom true/false questions about the receipt. For implementation guidance, see SmartValidate Implementation.

Field	Type	Description	Required
`smartValidate.prompts`	object[]	One to three prompts.	No
`smartValidate.prompts[].question`	string	The question Taggun should answer from the receipt.	Yes
`smartValidate.prompts[].example`	object	A single expected boolean output key and value, for example `{ "is_credit_card": true }`.	Yes
`smartValidate.prompts[].skip`	boolean	When `true`, the prompt result can still be returned but is not added as a validation check. Defaults to `false`.	No

Example Request

{
  "date": {
    "start": "2026-06-01T00:00:00.000Z",
    "end": "2026-06-30T23:59:59.999Z"
  },
  "merchantNames": {
    "allowList": ["Fresh Market"],
    "blockList": ["Fresh Market Wholesale"]
  },
  "productCodes": {
    "description": "Find product codes printed beside eligible coffee products",
    "list": ["COF-250", "COF-500"]
  },
  "productLineItems": {
    "names": ["Coffee Beans"],
    "quantity": {
      "min": 1,
      "max": 5
    },
    "totalPrice": {
      "min": 5,
      "max": 80
    }
  },
  "balanceOwing": {
    "max": 0
  },
  "fraudDetection": {
    "allowSimilarityCheck": true
  },
  "smartValidate": {
    "prompts": [
      {
        "question": "Was this paid by credit card?",
        "example": {
          "is_credit_card": true
        }
      }
    ]
  }
}

Response

Successful creation returns HTTP 201.

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

If the campaign ID already exists, the API returns a 400 response with the message Campaign id already exists.

Next Step

After creating settings, submit receipts with Validate Receipts.