Elastic Path Custom Discounts API

openapi: 3.2.0
info:
  title: Carts, Checkout, Orders Introduction Custom Discounts API
  description: 'A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.


    A cart item identifies the product, the product price, the quantity selected, and the total price for the quantity selected. The cart displays a running total of the cost for the selected products plus the calculated tax.


    You can allow your shoppers to add custom text to a product when adding an item to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. See [Add product to cart](/docs/api/carts/manage-carts#add-product-to-cart).


    After a shopper checks out, the cart is converted to an order, and you can manually delete the cart. If you don''t delete the cart, it is purged automatically after seven days.


    The preview cart feature allows you to set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart. See [Create a Preview Cart](/docs/api/carts/create-a-cart#preview-cart).


    The following diagram shows a typical cart workflow:


    ![Shows a cart workflow, starting from adding the first item to a cart, through cart creation and checkout](/assets/cart-workflow.png)


    ### Multiple Carts


    Buyers often make purchases based on jobs that they need to perform or outcomes they need to achieve and therefore require more than one shopping cart. For example, a corporate buyer places orders for multiple locations. Each location has a different frequency of ordering and require different products. The buyer can create one cart per location, fill the carts, and then check out the carts quickly. Similarly, shoppers can also create multiple carts for the ease of managing various shopping experiences, such as birthdays or holidays.


    Each cart is discrete and separate. Any updates or changes to one cart has no effect on the other carts. A cart persists, that is, it stays with the buyer or shopper even after they use the cart in a checkout. Carts remain available after a checkout.

    '
  contact:
    name: Elastic Path
    url: https://elasticpath.com
  version: 26.0313.7324347
  x-version-timestamp: 2026-03-13 21:22:42+00:00
  license:
    name: MIT
    url: assets/LICENSE
servers:
- url: https://useast.api.elasticpath.com
  description: US East Production Server
  variables: {}
- url: https://euwest.api.elasticpath.com
  description: EU West Production Server
  variables: {}
security:
- bearerAuth: []
tags:
- name: Custom Discounts
  description: 'With custom discounts, you can allow your shoppers to apply discounts from external services to their purchases. To apply custom discounts to carts and cart items, you need to set `custom_discounts_enabled` field to `true` in your [Cart Settings](/docs/api/carts/put-v-2-settings-cart).


    You cannot add custom discounts to an empty cart.


    :::caution


    - You can apply up to five custom discounts to cart and cart item.

    - The stores that use [simple calculation method](/guides/How-To/Carts/calculate-totals) do not support custom discounts.


    :::

    '
paths:
  /v2/carts/{cartID}/custom-discounts:
    parameters: []
    post:
      tags:
      - Custom Discounts
      summary: Bulk Add Custom Discounts to Cart
      description: 'The default value for custom discounts on both the cart and cart items is set to 5 if this parameter is not configured in the store. To verify the custom discount limit value, call [Get all settings](/docs/api/settings/get-v-2-settings) endpoint.


        To increase the custom discount value, contact [Elastic Path Support team](https://support.elasticpath.com/hc/en-us).

        '
      operationId: bulkAddCustomDiscountsToCart
      parameters:
      - name: cartID
        in: path
        description: Specifies the system generated ID for the cart that the shopper created.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartsBulkCustomDiscounts'
        required: false
      responses:
        '201':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CartsBulkCustomDiscountsResponse'
                - $ref: '#/components/schemas/CartsBulkCustomDiscountsCollectionResponse'
        '400':
          description: Could not apply custom discount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  summary: Custom discounts not enabled for this cart
                  value:
                    errors:
                    - detail: Custom discounts not enabled for this cart
                      status: 400
                      title: Bad Request
        '422':
          description: Could not apply custom discount
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
                examples:
                  summary: Exceeded custom discount limit
                  value:
                    errors:
                    - detail: Cannot exceed custom discount limit of (1) at the cart level.
                      status: 422
                      title: Custom discount not added to cart
      deprecated: false
    delete:
      tags:
      - Custom Discounts
      summary: Bulk Delete Custom Discounts From Cart
      description: Use this endpoint to bulk delete custom discounts from cart.
      operationId: bulkDeleteCustomDiscountsFromCart
      parameters:
      - name: cartID
        in: path
        description: Specifies the unique ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
      deprecated: false
  /v2/carts/{cartID}/custom-discounts/{customdiscountID}:
    parameters: []
    put:
      tags:
      - Custom Discounts
      summary: Update Custom Discount For Cart
      description: Use this endpoint to update a custom discount in your cart.
      operationId: updateCustomDiscountForCart
      parameters:
      - name: cartID
        in: path
        description: Specifies the unique ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      - name: customdiscountID
        in: path
        description: Specifies the ID for the custom discount to be updated.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartsCustomDiscountsEntityRequest'
        required: false
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse'
      deprecated: false
    delete:
      tags:
      - Custom Discounts
      summary: Delete Custom Discount From Cart
      description: Use this endpoint to delete custom discount from cart.
      operationId: deleteCustomDiscountFromCart
      parameters:
      - name: cartID
        in: path
        description: Specifies the unique ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      - name: customdiscountID
        in: path
        description: Specifies the ID for the custom discount to be deleted.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
      deprecated: false
  /v2/carts/{cartID}/items/{cartitemID}/custom-discounts:
    parameters: []
    post:
      tags:
      - Custom Discounts
      summary: Add Custom Discount To Cart Item
      description: Use this endpoint to add a custom discount to cart item.
      operationId: addCustomDiscountToCartItem
      parameters:
      - name: cartID
        in: path
        description: Specifies the ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      - name: cartitemID
        in: path
        description: Specifies the unique identifier for the cart item.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CartsCustomDiscountsObject'
      responses:
        '201':
          description: Successful request
          headers: {}
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/CartsCustomDiscountsCollectionResponse'
                - $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                default:
                  summary: Required field missing
                  value:
                    errors:
                    - detail: Custom discounts not enabled for this cart
                      status: 400
                      title: Bad Request
        '422':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response.ErrorResponse'
              examples:
                default:
                  summary: Discount Limit Reached
                  value:
                    errors:
                    - detail: Custom discount limit reached for this cart item
                      status: 422
                      title: Limit Reached
      deprecated: false
  /v2/carts/{cartID}/items/{cartitemID}/custom-discounts/{customdiscountID}:
    parameters: []
    put:
      tags:
      - Custom Discounts
      summary: Update Custom Discount For Cart Item
      description: Use this endpoint to update a custom discount in your cart item.
      operationId: updateCustomDiscountForCartItem
      parameters:
      - name: cartID
        in: path
        description: Specifies the ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      - name: cartitemID
        in: path
        description: Specifies the ID for the cart item.
        required: true
        style: simple
        schema:
          type: string
      - name: customdiscountID
        in: path
        description: Specifies the ID for the custom discount to be updated.
        required: true
        style: simple
        schema:
          type: string
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CartsCustomDiscountsEntityRequest'
      responses:
        '200':
          description: ''
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse'
      deprecated: false
    delete:
      tags:
      - Custom Discounts
      summary: Delete Custom Discount From Cart Item
      description: Use this endpoint to delete custom discount from cart item.
      operationId: deleteCustomDiscountFromCartItem
      parameters:
      - name: cartID
        in: path
        description: Specifies the ID for the cart.
        required: true
        style: simple
        schema:
          type: string
      - name: cartitemID
        in: path
        description: Specifies the ID for the cart item.
        required: true
        style: simple
        schema:
          type: string
      - name: customdiscountID
        in: path
        description: Specifies the ID for the custom discount to be deleted.
        required: true
        style: simple
        schema:
          type: string
      responses:
        '204':
          description: No Content
          headers: {}
          content: {}
      deprecated: false
components:
  schemas:
    Response.ErrorResponse:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
    CartsCustomDiscountsEntityResponse:
      type: object
      properties:
        data:
          type: object
          $ref: '#/components/schemas/CartsCustomDiscountsObject'
    AddAllOrNothingOptionsObject:
      title: Add All Or Nothing Options Object
      type: object
      properties:
        add_all_or_nothing:
          description: When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`.
          type: boolean
          examples:
          - false
    CartsCustomDiscountsResponseObject:
      title: CartsCustomDiscountsResponse
      type: object
      properties:
        amount:
          type: object
          properties:
            amount:
              description: Specifies an amount to be applied for the custom discount. It must be less than zero.
              type: number
              examples:
              - -1000
            currency:
              description: The currency set for the custom discount.
              type: string
              examples:
              - USD
            formatted:
              description: The formatted value for the custom discount.
              type: string
              examples:
              - -$10.00
        description:
          description: Specifies a description for the custom discount.
          type: string
          examples:
          - Custom discount description
        discount_code:
          description: Specifies the discount code used for the custom discount.
          type: string
          examples:
          - cart-custom-promo-code
        discount_engine:
          description: Specifies from where the custom discount is applied. For example, Talon.one.
          type: string
          examples:
          - Custom Discount Engine
        external_id:
          description: Specifies an external id for the custom discount.
          type: string
          examples:
          - custom-discount-external-id
        type:
          description: Specifies the type of the resource. Always `custom_discount`.
          type: string
          const: custom_discount
        id:
          description: Specifies the UUID of the custom discount.
          type: string
          format: uuid
          readOnly: true
          examples:
          - 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9
        relationships:
          description: Relationships to other resources like cart items
          type: object
          properties:
            item:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The item ID this discount is related to
                    type:
                      type: string
                      enum:
                      - cart_item
                      - custom_item
    CartItemBulkCustomDiscountObject:
      title: CartItemBulkCustomDiscountObject
      type: object
      allOf:
      - $ref: '#/components/schemas/CartsCustomDiscountsObject'
      - $ref: '#/components/schemas/CustomDiscountRelationshipsCartItemRequest'
    CartsBulkCustomDiscountsCollectionResponse:
      title: CartsBulkCustomDiscountsCollectionResponse
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CartsCustomDiscountsObject'
        errors:
          type: array
          description: Array of validation or processing errors
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
    CartsCustomDiscountsEntityRequest:
      type: object
      properties:
        data:
          type: object
          $ref: '#/components/schemas/CartsCustomDiscountsResponseObject'
    CartsBulkCustomDiscounts:
      title: CartsBulkCustomDiscounts
      type: object
      properties:
        data:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/CartsCustomDiscountsObject'
            - $ref: '#/components/schemas/CartItemBulkCustomDiscountObject'
        options:
          $ref: '#/components/schemas/AddAllOrNothingOptionsObject'
    CartsBulkCustomDiscountsResponse:
      title: CartsBulkCustomDiscountsResponse
      type: object
      properties:
        data:
          type: object
          $ref: '#/components/schemas/CartsCustomDiscountsObject'
        errors:
          type: array
          description: Array of validation or processing errors
          items:
            $ref: '#/components/schemas/Response.ErrorItem'
    CustomDiscountRelationshipsCartItemRequest:
      title: CustomDiscountRelationshipsCartItemRequest
      type: object
      properties:
        relationships:
          type: object
          properties:
            item:
              type: object
              properties:
                data:
                  type: object
                  required:
                  - type
                  - id
                  properties:
                    type:
                      description: Specifies the type of item. For example, `custom_item` or `cart_item`.
                      type: string
                      examples:
                      - cart_item
                    id:
                      description: Specifies the unique identifier of the `cart_item` or `custom_item` in the cart.
                      type: string
                      format: uuid
                      examples:
                      - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6
    Response.ErrorItem:
      type: object
      required:
      - status
      - title
      properties:
        title:
          type: string
          description: A brief summary of the error.
          examples:
          - Bad Request
        status:
          type:
          - string
          - integer
          description: The HTTP response code of the error.
          examples:
          - '400'
        detail:
          type: string
          description: Optional additional detail about the error.
          examples:
          - The field 'name' is required
        source:
          type: string
          description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity').
        meta:
          type: object
          description: Additional metadata associated with the error. May include arbitrary keys.
          properties:
            id:
              type: string
              description: The resource id associated with the error
            ids:
              type: array
              items:
                type: string
                description: The resource ids associated with the error
            item_ids:
              type: array
              items:
                type: string
                description: The cart_item ids associated with the error
            shipping_group_id:
              type: string
              description: The shipping group id associated with the error
            shipping_group_ids:
              type: array
              items:
                type: string
                description: The shipping group ids associated with the error
            cart_id:
              type: string
              description: The cart id associated with the error
            code:
              type: string
              description: The code associated with the error.
            order_id:
              type: string
              description: The order id associated with the error.
            sku:
              type: string
              description: The SKU associated with the error.
            email:
              type: string
              format: email
              description: The email address associated with the error.
            component_product_id:
              type: string
              format: uuid
              description: The component product ID associated with the error.
            error-meta-key:
              type: string
              description: Custom error metadata key used for additional error context (e.g., in payment rejections).
            value:
              description: The value associated with the error.
              oneOf:
              - type: string
              - type: integer
              - type: boolean
              - type: object
                additionalProperties: true
              - type: array
    CartsCustomDiscountsObject:
      title: CartsCustomDiscountsObject
      type: object
      required:
      - amount
      - description
      - discount_code
      - discount_engine
      - external_id
      - type
      properties:
        amount:
          type: object
          oneOf:
          - type: number
            examples:
            - -1000
          - type: object
            properties:
              amount:
                type: number
                examples:
                - -1000
              currency:
                type: string
                examples:
                - USD
              formatted:
                type: string
                examples:
                - -$10.00
        description:
          description: Specifies a description for the custom discount.
          type: string
          examples:
          - Custom discount description
        discount_code:
          description: Specifies the discount code used for the custom discount.
          type: string
          examples:
          - cart-custom-promo-code
        discount_engine:
          description: Specifies from where the custom discount is applied. For example, Talon.one.
          type: string
          examples:
          - Custom Discount Engine
        external_id:
          description: Specifies an external id for the custom discount.
          type: string
          examples:
          - custom-discount-external-id
        type:
          description: Specifies the type of the resource. Always `custom_discount`.
          type: string
          const: custom_discount
        id:
          description: Specifies the UUID of the custom discount.
          type: string
          format: uuid
        relationships:
          description: Relationships to other resources like cart items
          type: object
          properties:
            item:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    id:
                      type: string
                      format: uuid
                      description: The item ID this discount is related to
                    type:
                      type: string
                      enum:
                      - cart_item
                      - custom_item
    CartsCustomDiscountsCollectionResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            $ref: '#/components/schemas/CartsCustomDiscountsObject'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer