TrellisDevelopers
API reference

Promotions

List promotions

GET
/promotion

Commerce7-style automatic discount promotions. Supports full CRUD plus query-based search to match the docs page behavior.

Query Parameters

q?string

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/promotion" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "promotions": [    {      "id": "string",      "title": "string",      "actionMessage": "string",      "usageLimitType": "Unlimited",      "usageLimit": 0,      "appliesTo": "Store",      "appliesToObjectIds": [        "string"      ],      "productDiscountType": "No Discount",      "productDiscount": 0,      "shippingDiscountType": "No Discount",      "shippingDiscount": 0,      "startDate": "2019-08-24T14:15:22Z",      "endDate": "2019-08-24T14:15:22Z",      "status": "Enabled",      "minimumCartAmount": 0,      "availableTo": "Everyone",      "availableToObjectIds": [        "string"      ],      "combinability": "combinable",      "requiresManagerApproval": true,      "excludesServiceCharges": true,      "serviceChargeInteraction": "pre_discount",      "maxDiscountAmount": 0,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "promotionSets": [        {          "id": "string"        }      ],      "offerType": "STANDARD",      "buyProductIds": [        "string"      ],      "buyQuantity": 0,      "getProductIds": [        "string"      ],      "getQuantity": 0,      "getDiscountPercent": 0,      "comboProductIds": [        "string"      ],      "comboFixedPrice": 0,      "usageLimitScope": "Global",      "usageLimitWindowMinutes": 0    }  ],  "total": 0}

Create a promotion

POST
/promotion

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X POST "https://example.com/promotion" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'
{  "id": "string",  "title": "string",  "actionMessage": "string",  "usageLimitType": "Unlimited",  "usageLimit": 0,  "appliesTo": "Store",  "appliesToObjectIds": [    "string"  ],  "productDiscountType": "No Discount",  "productDiscount": 0,  "shippingDiscountType": "No Discount",  "shippingDiscount": 0,  "startDate": "2019-08-24T14:15:22Z",  "endDate": "2019-08-24T14:15:22Z",  "status": "Enabled",  "minimumCartAmount": 0,  "availableTo": "Everyone",  "availableToObjectIds": [    "string"  ],  "combinability": "combinable",  "requiresManagerApproval": true,  "excludesServiceCharges": true,  "serviceChargeInteraction": "pre_discount",  "maxDiscountAmount": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "promotionSets": [    {      "id": "string"    }  ],  "offerType": "STANDARD",  "buyProductIds": [    "string"  ],  "buyQuantity": 0,  "getProductIds": [    "string"  ],  "getQuantity": 0,  "getDiscountPercent": 0,  "comboProductIds": [    "string"  ],  "comboFixedPrice": 0,  "usageLimitScope": "Global",  "usageLimitWindowMinutes": 0}

Retrieve a promotion

GET
/promotion/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

application/json

curl -X GET "https://example.com/promotion/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
{  "id": "string",  "title": "string",  "actionMessage": "string",  "usageLimitType": "Unlimited",  "usageLimit": 0,  "appliesTo": "Store",  "appliesToObjectIds": [    "string"  ],  "productDiscountType": "No Discount",  "productDiscount": 0,  "shippingDiscountType": "No Discount",  "shippingDiscount": 0,  "startDate": "2019-08-24T14:15:22Z",  "endDate": "2019-08-24T14:15:22Z",  "status": "Enabled",  "minimumCartAmount": 0,  "availableTo": "Everyone",  "availableToObjectIds": [    "string"  ],  "combinability": "combinable",  "requiresManagerApproval": true,  "excludesServiceCharges": true,  "serviceChargeInteraction": "pre_discount",  "maxDiscountAmount": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "promotionSets": [    {      "id": "string"    }  ],  "offerType": "STANDARD",  "buyProductIds": [    "string"  ],  "buyQuantity": 0,  "getProductIds": [    "string"  ],  "getQuantity": 0,  "getDiscountPercent": 0,  "comboProductIds": [    "string"  ],  "comboFixedPrice": 0,  "usageLimitScope": "Global",  "usageLimitWindowMinutes": 0}

Delete a promotion

DELETE
/promotion/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Response Body

curl -X DELETE "https://example.com/promotion/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123"
Empty

Update a promotion

PUT
/promotion/{id}

Path Parameters

id*string
Length1 <= length

Header Parameters

x-tenant-id?string

Selects the tenant by id. When both tenant headers are omitted, the server falls back to the configured default tenant slug.

x-tenant-slug?string

Selects the tenant by slug. Use this when you know the tenant slug instead of the tenant id.

x-location-id?string

Adds a location scope to the request for location-aware reads, writes, and audit entries.

x-auth-provider?"hexclave"

Test-only Hexclave provider identifier used with x-auth-user-id when trusted identity headers are explicitly enabled. Production clients must use a Hexclave bearer token.

Value in

  • "hexclave"
x-auth-user-id?string

Temporary auth subject used to resolve the acting staff user through the staff auth identity mapping.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X PUT "https://example.com/promotion/string" \  -H "x-tenant-id: tenant-local" \  -H "x-tenant-slug: trellis-local" \  -H "x-location-id: loc-tasting-room" \  -H "x-auth-provider: hexclave" \  -H "x-auth-user-id: user_abc123" \  -H "Content-Type: application/json" \  -d '{}'
{  "id": "string",  "title": "string",  "actionMessage": "string",  "usageLimitType": "Unlimited",  "usageLimit": 0,  "appliesTo": "Store",  "appliesToObjectIds": [    "string"  ],  "productDiscountType": "No Discount",  "productDiscount": 0,  "shippingDiscountType": "No Discount",  "shippingDiscount": 0,  "startDate": "2019-08-24T14:15:22Z",  "endDate": "2019-08-24T14:15:22Z",  "status": "Enabled",  "minimumCartAmount": 0,  "availableTo": "Everyone",  "availableToObjectIds": [    "string"  ],  "combinability": "combinable",  "requiresManagerApproval": true,  "excludesServiceCharges": true,  "serviceChargeInteraction": "pre_discount",  "maxDiscountAmount": 0,  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "promotionSets": [    {      "id": "string"    }  ],  "offerType": "STANDARD",  "buyProductIds": [    "string"  ],  "buyQuantity": 0,  "getProductIds": [    "string"  ],  "getQuantity": 0,  "getDiscountPercent": 0,  "comboProductIds": [    "string"  ],  "comboFixedPrice": 0,  "usageLimitScope": "Global",  "usageLimitWindowMinutes": 0}

Products

Previous Page

Reservations

Next Page