Offers

The offers resource represents a deal available from the group of stores defined by a particular campaign. For example, you could create an offer that provides $50 in store credit for the cost of $30 and associate that with a campaign containing MyStore1 and MyStore2. You can then purchase and associate the offer with users by creating an offer order for each user. The users can then use their cards to spend the $50 in store credit at MyStore1 or MyStore2.

Create offer

Action: POST
Endpoint: /offers

Use this endpoint to create an offer. Add the offer details to the body of the request in JSON format.

When you create any Marqeta resource, the system associates a token for referencing that resource. You can create your own token using up to 36 alphanumeric characters. If you do not include a token value, one is generated automatically.

Body field details

Name Type Required? Description Allowable Values
token string No The unique identifier of the offer.

If you do not include a token, the system will generate one automatically. This token is necessary for use in other API calls, so we recommend that rather than let the system generate one, you use a simple string that is easy to remember. This value cannot be updated.
36 char max
name string Yes The name of the offer. 40 char max
currency_code string Yes The currency the offer accepts. 3-digit ISO code.

840 currently supported.
purchase_amount decimal Yes The amount for which the offer was purchased. 0.00
reward_amount decimal Yes The amount to be rewarded to the card holder if the trigger amount is exceeded.

Do not include the purchase_amount in the reward_amount. The reward_amount and purchase_amount are credited to the MSA separately.
0.00
campaign_token string Yes The unique identifier of the campaign the offer is associated with. Existing campaign token.

Issue a GET to /campaigns to retrieve campaign tokens.
active boolean No Indicates whether the offer is active. true | false

Default: true
reward_trigger_amount decimal No The amount the cardholder needs to spend in order to get the reward amount. 0.00
start_date string No The date the offer begins. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
end_date string No The date the offer ends. If the offer is set to active=false before the end_date (if any), then the offer will be deactivated. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

Sample request body

{
"token": "my_offer",
"active": "true",
"name": "May_offer",
"currency_code": "840",
"purchase_amount": "200",
"reward_amount": "50",
"campaign_token": "my_campaign"
}

Sample response body

{
"token": "my_offer",
"active": "true",
"name": "May_offer",
"currency_code": "840",
"purchase_amount": "200",
"reward_trigger_amount": 50,
"reward_amount": "50",
"campaign_token": "my_campaign"
}


Retrieve offer

Action: GET
Endpoint: /offers/{token}

Use this endpoint to retrieve a specific offer. Include the offer token path parameter to specify the offer to return.

This endpoint supports field filtering.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the offer to retrieve. Existing offer token.

Issue a GET to /offers to retrieve offer tokens.

Sample response body

{
"token": "my_offer",
"active": true,
"name": "May_offer",
"reward_amount": 50,
"spend_amount": 200,
"reward_trigger_amount": 50,
"campaign_token": "my_campaign",
"currency_code": "840"
}


Update offer

Action: PUT
Endpoint: /offers/{token}

Use this endpoint to update an offer. Include the offer token path parameter to specify the offer to update. Add the offer details to the body of the request in JSON format. Only values of parameters in the request are modified; all others are left unchanged.

URL path parameters

Name Type Required? Description Allowable Values
token string Yes Identifies the offer to update. Existing offer token.

Issue a GET to /offers to retrieve offer tokens.

Body field details

Name Type Required? Description Allowable Values
name string No The name of the offer. 40 char max
active boolean No Indicates whether the offer is active. true | false

Default: true
start_date string No The date the offer begins. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z
end_date string No The date the offer ends. If the offer has the active field = false before the end_date is reached (if any), then the offer will be deactivated. yyyy-MM-dd, yyyy-DD-mmT00:00:00Z

Sample request body

{
"start_date": "2014-12-01",
"end_date": "2015-01-01"
}

Sample response body

{
"token": "my_offer",
"active": "true",
"name": "May_offer",
"start_date": "2014-12-01",
"end_date": "2015-01-01",
"currency_code": "840",
"purchase_amount": "200",
"reward_trigger_amount": 50,
"reward_amount": "50",
"campaign_token": "my_campaign"
}


List offers

Action: GET
Endpoint: /offers

Use this endpoint to list existing offers.

This endpoint supports field filtering and pagination.

Sample response body

{
"count": 5,
"start_index": 0,
"end_index": 1,
"is_more": true,
"data": [
{
"token": "my_offer",
"active": true,
"name": "Monthly Order",
"start_date": "2014-12-01T00:00:00Z",
"end_date": "2014-12-31T00:00:00Z",
"reward_amount": 0,
"purchase_amount": 200,
"reward_trigger_amount": 0.01,
"campaign_token": "my_campaign",
"currency_code": "840"
},
{
"token": "a7d40769-0b30-4fd2-be7b-0f9bcb457a87",
"active": true,
"name": "GiftOrder - a7d40769-0b30-4fd2-be7b-0f9bcb457a87",
"reward_amount": 0,
"purchase_amount": 50,
"reward_trigger_amount": 0.01,
"campaign_token": "my_campaign2",
"currency_code": "USD"
}
]
}