Coupons

Coupons are discount codes you can create for your SMBcrm account. Use this API to list the coupons you already have, look up a single coupon, create new ones, update them, and delete them.

Base URL: https://services.smbcrm.com · Version header: v3 · Scopes: payments/coupons.readonly (read), payments/coupons.write (create, update, and delete). See Scopes.

List coupons

GET/payments/coupon/list

List the coupons configured in your SMBcrm account.

scope payments/coupons.readonlyauth Location token or PIT

Identify your account with altId + altType=location, the same convention used elsewhere in the Payments API. Filter by status, search by name or code with search, and page through results with limit / offset.

curl "https://services.smbcrm.com/payments/coupon/list?altId=<location_id>&altType=location&status=active&limit=20&offset=0" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

{
  "data": [
    {
      "_id": "<coupon_id>",
      "altId": "<location_id>",
      "altType": "location",
      "name": "Summer Sale",
      "code": "SUMMER25",
      "discountType": "percentage",
      "discountValue": 25,
      "status": "active",
      "startDate": "2026-06-01T00:00:00.000Z",
      "endDate": "2026-08-31T23:59:59.000Z",
      "usageCount": 12,
      "limitPerCustomer": 0,
      "applyToFuturePayments": false,
      "applyToFuturePaymentsConfig": { "type": "forever" },
      "createdAt": "2026-06-15T09:00:00.000Z",
      "updatedAt": "2026-06-15T09:00:00.000Z"
    }
  ],
  "totalCount": 1,
  "traceId": "<trace_id>"
}

Query param	Type	Required	Description
`altId`	string	Yes	Your `<location_id>`.
`altType`	string	Yes	Always `location`.
`status`	string	No	Filter by coupon status: `scheduled`, `active`, or `expired`.
`search`	string	No	Filter coupons by a search term.
`limit`	number	No	Maximum number of coupons to return per page.
`offset`	number	No	Number of coupons to skip, for pagination.

Get a coupon

GET/payments/coupon

Fetch a single coupon by id and code.

scope payments/coupons.readonlyauth Location token or PIT

Identify the coupon with id and code, along with your account ID.

curl "https://services.smbcrm.com/payments/coupon?altId=<location_id>&altType=location&id=<coupon_id>&code=SUMMER25" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

{
  "_id": "<coupon_id>",
  "altId": "<location_id>",
  "altType": "location",
  "name": "Summer Sale",
  "code": "SUMMER25",
  "discountType": "percentage",
  "discountValue": 25,
  "status": "active",
  "startDate": "2026-06-01T00:00:00.000Z",
  "endDate": "2026-08-31T23:59:59.000Z",
  "usageCount": 12,
  "limitPerCustomer": 0,
  "applyToFuturePayments": false,
  "applyToFuturePaymentsConfig": { "type": "forever" },
  "createdAt": "2026-06-15T09:00:00.000Z",
  "updatedAt": "2026-06-15T09:00:00.000Z",
  "traceId": "<trace_id>"
}

Query param	Type	Required	Description
`altId`	string	Yes	Your `<location_id>`.
`altType`	string	Yes	Always `location`.
`id`	string	Yes	The coupon’s `_id`.
`code`	string	Yes	The coupon’s code.

Create a coupon

POST/payments/coupon

Create a coupon in your SMBcrm account.

scope payments/coupons.writeauth Location token or PIT

Send your account ID plus the coupon’s name, code, discountType, discountValue, and startDate. discountType is either percentage or amount; discountValue is the percent off (0–100) or the flat amount off, respectively.

curl -X POST https://services.smbcrm.com/payments/coupon \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "altId": "<location_id>",
    "altType": "location",
    "name": "Summer Sale",
    "code": "SUMMER25",
    "discountType": "percentage",
    "discountValue": 25,
    "startDate": "2026-06-01T00:00:00.000Z",
    "endDate": "2026-08-31T23:59:59.000Z",
    "usageLimit": 500
  }'

{
  "_id": "<coupon_id>",
  "altId": "<location_id>",
  "altType": "location",
  "name": "Summer Sale",
  "code": "SUMMER25",
  "discountType": "percentage",
  "discountValue": 25,
  "status": "active",
  "startDate": "2026-06-01T00:00:00.000Z",
  "endDate": "2026-08-31T23:59:59.000Z",
  "usageCount": 0,
  "limitPerCustomer": 0,
  "applyToFuturePayments": false,
  "applyToFuturePaymentsConfig": { "type": "forever" },
  "createdAt": "2026-07-08T15:04:00.000Z",
  "updatedAt": "2026-07-08T15:04:00.000Z",
  "traceId": "<trace_id>"
}

Cap total redemptions with usageLimit, and restrict the coupon to specific catalog items with productIds, priceIds, or variantIds. Set applyToFuturePayments to true to apply the discount to a subscription’s future charges, and describe how long with applyToFuturePaymentsConfig (type is forever or fixed; when fixed, also set duration and durationType).

Update a coupon

PUT/payments/coupon

Update an existing coupon.

scope payments/coupons.writeauth Location token or PIT

This endpoint has no coupon ID in the path, so identify the coupon in the request body with id. PUT replaces the coupon’s fields, so altId, altType, name, code, discountType, discountValue, and startDate are all required alongside id, even if you’re only changing one value.

curl -X PUT https://services.smbcrm.com/payments/coupon \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "<coupon_id>",
    "altId": "<location_id>",
    "altType": "location",
    "name": "Summer Sale",
    "code": "SUMMER25",
    "discountType": "percentage",
    "discountValue": 20,
    "startDate": "2026-06-01T00:00:00.000Z",
    "endDate": "2026-08-31T23:59:59.000Z"
  }'

Delete a coupon

DELETE/payments/coupon

Permanently delete a coupon.

scope payments/coupons.writeauth Location token or PIT

This endpoint also has no coupon ID in the path. Identify the coupon in the request body with id, alongside your account ID.

curl -X DELETE https://services.smbcrm.com/payments/coupon \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3" \
  -H "Content-Type: application/json" \
  -d '{
    "altId": "<location_id>",
    "altType": "location",
    "id": "<coupon_id>"
  }'

{
  "success": true,
  "traceId": "<trace_id>"
}

Payments overview — scopes, the altId/altType convention, and the rest of the Payments API.
Products & Prices — your product catalog and the prices attached to each product.
Invoices & Estimates — one-off billing documents you create and send to a contact.
Scopes — permissions reference for payments/coupons.readonly and payments/coupons.write.

Coupons

List coupons

Get a coupon

Create a coupon

Update a coupon

Delete a coupon

Related