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": true,
      "applyToFuturePaymentsConfig": { "type": "forever" },
      "productIds": ["<product_id>"],
      "priceIds": ["<price_id>"],
      "variantIds": [],
      "userId": "<user_id>",
      "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 name or code.
`limit`	number	No	Maximum number of coupons to return per page. Defaults to `100`.
`offset`	number	No	Number of coupons to skip, for pagination. Defaults to `0`.

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": true,
  "applyToFuturePaymentsConfig": { "type": "forever" },
  "userId": "<user_id>",
  "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 or the flat amount off, respectively. Create returns 201 Created; update and delete return 200 OK. A request that fails validation returns 422. See Errors & Troubleshooting.

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": true,
  "applyToFuturePaymentsConfig": { "type": "forever" },
  "userId": "<user_id>",
  "createdAt": "2026-07-08T15:04:00.000Z",
  "updatedAt": "2026-07-08T15:04:00.000Z",
  "traceId": "<trace_id>"
}

Body field	Type	Required	Description
`altId`	string	Yes	Your `<location_id>`.
`altType`	string	Yes	Always `location`.
`name`	string	Yes	The coupon’s name.
`code`	string	Yes	The code customers enter.
`discountType`	string	Yes	`percentage` or `amount`.
`discountValue`	number	Yes	The percent off or the flat amount off, matching `discountType`.
`startDate`	string	Yes	When the coupon becomes active, as an ISO 8601 date-time such as `2026-06-01T00:00:00.000Z`.
`endDate`	string	No	When the coupon expires, in the same format.
`usageLimit`	number	No	Maximum number of times the coupon can be used in total.
`productIds`	string[]	No	Restrict the coupon to these products.
`priceIds`	string[]	No	Restrict the coupon to these prices.
`variantIds`	string[]	No	Restrict the coupon to these product variants.
`applyToFuturePayments`	boolean	No	Whether the discount also applies to a subscription’s upcoming charges. Defaults to `true`.
`applyToFuturePaymentsConfig`	object	No	How long the discount keeps applying to those charges. Defaults to `{ "type": "forever" }`.
`limitPerCustomer`	boolean	No	Send `true` to let each customer redeem the coupon once. Defaults to `false`.

applyToFuturePayments defaults to true, so a coupon applies to a subscription’s upcoming charges unless you send false, which makes the coupon one-time only.

applyToFuturePaymentsConfig takes three fields, and all three are required when you send it: type (forever or fixed), duration (a number of months), and durationType (always months). To keep the discount on a subscription for three months, send:

{
  "applyToFuturePayments": true,
  "applyToFuturePaymentsConfig": {
    "type": "fixed",
    "duration": 3,
    "durationType": "months"
  }
}

Requests take limitPerCustomer as a boolean, but responses return it as a number: the most times one customer can redeem the coupon, where 0 means no limit. Responses don’t include usageLimit; usageCount shows how many times the coupon has been used.

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. Send altId, altType, name, code, discountType, discountValue, and startDate alongside id on every update, even if you’re only changing one value. The optional fields are the same as for create, and the response is 200 OK with the updated coupon.

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"
  }'

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

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