openapi: 3.0.0 info: title: BigCommerce Abandoned Cart Emails Coupons API version: 3.0.0 termsOfService: https://www.bigcommerce.com/terms description: Abandoned Cart Emails V3 API managing Handlebars-based emails. contact: name: BigCommerce url: https://www.bigcommerce.com email: support@bigcommerce.com servers: - url: https://api.bigcommerce.com/stores/{store_hash}/v3 variables: store_hash: default: store_hash description: Permanent ID of the BigCommerce store. description: BigCommerce API Gateway security: - X-Auth-Token: [] tags: - name: Coupons paths: /coupons: parameters: - $ref: '#/components/parameters/Accept' get: tags: - Coupons summary: BigCommerce Get All Coupons description: 'Returns a list of *Coupons*. Default sorting is by coupon/discount id, from lowest to highest. You can pass in optional filter parameters. We recommended using `?min_id=x&limit=y` to paginate through a large set of data because it offers better performance. ## Usage Notes Available types for `type` and `exclude_type` filters: |Type| |-| |`per_item_discount`| |`percentage_discount`| |`per_total_discount`| |`shipping_discount`| |`free_shipping`| |`promotion`| Coupons with `type=promotion` will not populate usable data for the following fields but instead be set to the following default values: ```json ... amount : 0.0000 min_purchase: 0.0000 applies_to restricted_to: [] shipping_methods : null ... ```' operationId: getCoupons parameters: - name: id in: query description: Optional filter param. `/api/v2/coupons?id={value}` schema: type: string - name: code in: query description: Optional filter param `/api/v2/coupons?code={value}` schema: type: string - name: name in: query description: Optional filter param `/api/v2/coupons?name={value}` schema: type: string - name: type in: query description: '|Type| |-| |`per_item_discount`| |`percentage_discount`| |`per_total_discount`| |`shipping_discount`| |`free_shipping`| |`promotion`|' schema: type: string - name: min_id in: query description: Optional filter param `/api/v2/coupons?min_id={value}` schema: exclusiveMaximum: false exclusiveMinimum: false type: integer - name: max_id in: query description: Optional filter param`/api/v2/coupons?max_id={value}` schema: exclusiveMaximum: false exclusiveMinimum: false type: integer - name: page in: query description: Number of pages `/api/v2/coupons?page={number}` schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: limit in: query description: Count per page `/api/v2/coupons?limit={count}` schema: exclusiveMaximum: false exclusiveMinimum: false type: number - name: exclude_type in: query description: '|Type| |-| |`per_item_discount`| |`percentage_discount`| |`per_total_discount`| |`shipping_discount`| |`free_shipping`| |`promotion`|' schema: type: string responses: '200': description: '' content: application/json: schema: type: array items: $ref: '#/components/schemas/coupon_Full' example: - id: 1 name: $5 off type: per_total_discount amount: '5.0000' min_purchase: '0.0000' expires: '' enabled: true code: S2549JM0Y applies_to: entity: categories ids: - 0 num_uses: 2 max_uses: 0 max_uses_per_customer: 0 restricted_to: {} shipping_methods: [] date_created: Tue, 13 Mar 2018 16:18:59 +0000 - id: 2 name: Limit by Location type: per_total_discount amount: '5.0000' min_purchase: '25.0000' expires: '' enabled: true code: E3JC79S0I applies_to: entity: categories ids: - 0 num_uses: 0 max_uses: 25 max_uses_per_customer: 0 restricted_to: countries: AU shipping_methods: - shipping_endicia date_created: Tue, 12 Jun 2018 20:22:19 +0000 post: tags: - Coupons summary: BigCommerce Create a New Coupon operationId: createCoupon description: 'Creates a *Coupon*. **Required Fields** * `name` * `code` * `type` * `amount` * `applies_to` **Read Only Fields** * `id` * `num_uses` **Notes** The coupon type can be one of the following: * `per_item_discount` * `per_total_discount` * `shipping_discount` * `free_shipping` * `percentage_discount` Legacy coupon codes only work with the store''s default currency. Applying a coupon with any other currency other than the store''s default will result in the error: "Coupons only apply to default currency."' parameters: - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/coupon_Base' required: true responses: '201': description: '' content: application/json: schema: $ref: '#/components/schemas/coupon_Full' example: id: 1 name: $5 off type: per_total_discount amount: '5.0000' min_purchase: '0.0000' expires: '' enabled: true code: S2549JM0Y applies_to: entity: categories ids: - 0 num_uses: 2 max_uses: 0 max_uses_per_customer: 0 restricted_to: {} shipping_methods: [] date_created: Tue, 13 Mar 2018 16:18:59 +0000 x-codegen-request-body-name: body delete: tags: - Coupons summary: BigCommerce Delete All Coupons description: '## Usage Notes * Deleting a coupon via this endpoint will delete the coupon but not the promotion it is attached to ' operationId: deleteCoupons parameters: - name: id:in in: query description: Optional param to identify a comma separated list of ids for coupons to delete in a batch. `/api/v2/coupons?id:in=1,2,3` schema: type: string responses: '204': description: '' content: {} /coupons/count: parameters: - $ref: '#/components/parameters/Accept' get: tags: - Coupons summary: BigCommerce Get a Count of Coupons description: Returns a count of all *Coupons* in the store. operationId: getCouponsCount responses: '200': description: '' content: application/json: schema: type: object properties: count: minimum: 0 type: integer example: count: 27 /coupons/{id}: parameters: - $ref: '#/components/parameters/Accept' - name: id in: path description: ID of the coupon. required: true schema: exclusiveMaximum: false exclusiveMinimum: false type: number put: tags: - Coupons summary: BigCommerce Update a Coupon description: 'Updates a *Coupon*. **Read Only Fields** * `id` * `num_uses` * `date_created` **Notes** If the `applies_to` value is cleared, you can restore it to the coupon by reapplying the `applies_to` value in a new `PUT` request.' operationId: updateCoupon parameters: - $ref: '#/components/parameters/ContentType' requestBody: content: application/json: schema: $ref: '#/components/schemas/coupon_Base' required: true responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/coupon_Full' example: id: 1 name: $5 off type: per_total_discount amount: '5.0000' min_purchase: '0.0000' expires: '' enabled: true code: S2549JM0Y applies_to: entity: categories ids: - 0 num_uses: 2 max_uses: 0 max_uses_per_customer: 0 restricted_to: {} shipping_methods: [] date_created: Tue, 13 Mar 2018 16:18:59 +0000 x-codegen-request-body-name: body delete: tags: - Coupons summary: BigCommerce Delete a Coupon description: Deletes a *Coupon*. operationId: deleteCoupon responses: '204': description: '' content: {} components: schemas: coupon_Base: title: coupon_Base required: - amount - applies_to - code - name - type type: object properties: name: type: string description: The name of the coupon. The value must be unique. example: Australia Customers Discount maxLength: 100 type: type: string enum: - per_item_discount - per_total_discount - shipping_discount - free_shipping - percentage_discount - promotion amount: type: string description: The discount to apply to an order, as either an amount or a percentage. This field’s usage is determined by the coupon `type`. For example, a `type` of + `percentage_discount` would determine a percentage here. example: '5' min_purchase: type: string description: Specifies a minimum value that an order must have before the coupon can be applied to it. example: '25' expires: type: string description: Specifies when a coupon expires. Coupons need not have an expiry date – you can also control expiry via + `max_uses` or `max_uses_per_customer`. If you do use this date field, the value must be in RFC 2822 format. enabled: type: boolean description: If the coupon is enabled, this field’s value is `true`; otherwise, `false`. example: true code: pattern: '[a-zA-Z0-9_\ -]' type: string description: The coupon code that customers will use to receive their discounts. Value must be unique. Only letters, numbers, white space, underscores, and hyphens are allowed. example: S2549JM0Y maxLength: 50 applies_to: type: object properties: ids: type: array description: ID of either the products or categories items: type: integer entity: type: string description: What the discount applies to. Can be products or categories. description: If it is not included in the PUT request, its existing value on the coupon will be cleared. Also required to be set on the POST request max_uses: type: integer description: Maximum number of times this coupon can be used. example: 25 max_uses_per_customer: type: integer description: Maximum number of times each customer can use this coupon. example: 0 restricted_to: type: object properties: countries: type: string shipping_methods: type: array description: This is a list of shipping-method names. A shipping method must be enabled on the store to use it with a coupon. To check which shipping methods are enabled, please use the [List Shipping Methods](/archive/store-operations/v2-catalog-products/v2-products#list-shipping-methods) endpoint. items: type: string example: id: 2 name: Australia Customers Discount type: per_item_discount amount: '5' min_purchase: '25' expires: '' enabled: true code: S2549JM0Y applies_to: entity: categories ids: - 0 - 3 num_uses: 0 max_uses: 25 max_uses_per_customer: 0 restricted_to: countries: AU shipping_methods: - shipping_endicia date_created: Tue, 13 Mar 2018 16:18:59 +0000 x-internal: false coupon_Full: title: coupon_Full allOf: - required: - id type: object properties: id: type: integer description: The coupon's ID. This is a read-only field; do not set or modify its value in a POST or PUT request. example: 2 date_created: type: string description: Date Created example: Tue, 13 Mar 2018 16:18:59 +0000 num_uses: type: integer description: Number of times this coupon has been used. This is a read-only field; do not set or modify its value in a POST or PUT request. example: 0 - $ref: '#/components/schemas/coupon_Base' x-internal: false parameters: Accept: name: Accept in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the response body. schema: type: string default: application/json ContentType: name: Content-Type in: header required: true description: The [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types) of the request body. schema: type: string default: application/json securitySchemes: X-Auth-Token: name: X-Auth-Token description: '### OAuth scopes | UI Name | Permission | Parameter | |:--|:--|:-| | Information & Settings | read-only | `store_v2_information_read_only`| | Information & Settings | modify | `store_v2_information` | ### Authentication header | Header | Argument | Description | |:-|:|:| | `X-Auth-Token` | `access_token` | For more about API accounts that generate `access_token`s, see our [Guide to API Accounts](/docs/start/authentication/api-accounts). | ### Further reading For example requests and more information about authenticating BigCommerce APIs, see [Authentication and Example Requests](/docs/start/authentication#x-auth-token-header-example-requests). For more about BigCommerce OAuth scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). For a list of API status codes, see [API Status Codes](/docs/start/about/status-codes).' type: apiKey in: header