Commerce Layer custom_promotion_rules API

openapi: 3.2.0
info:
  title: Commerce Layer Custom Promotion Rules API
  version: 7.10.1
  contact:
    name: API Support
    url: https://commercelayer.io
    email: support@commercelayer.io
  description: Headless Commerce for Global Brands.
servers:
- url: https://{your_organization_slug}.commercelayer.io/api
  description: API
- url: https://core.commercelayer.io/users/sign_in
  description: Sign in
- url: https://docs.commercelayer.io/api
  description: API reference
security:
- bearerAuth: []
tags:
- name: custom_promotion_rules
  description: resource type
paths:
  /custom_promotion_rules:
    get:
      operationId: GET/custom_promotion_rules
      summary: List all custom promotion rules
      description: List all custom promotion rules
      tags:
      - custom_promotion_rules
      responses:
        '200':
          description: A list of custom promotion rule objects
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/customPromotionRuleResponseList'
    post:
      operationId: POST/custom_promotion_rules
      summary: Create a custom promotion rule
      description: Create a custom promotion rule
      tags:
      - custom_promotion_rules
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/customPromotionRuleCreate'
      responses:
        '201':
          description: The created custom promotion rule object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/customPromotionRuleResponse'
  /custom_promotion_rules/{customPromotionRuleId}:
    get:
      operationId: GET/custom_promotion_rules/customPromotionRuleId
      summary: Retrieve a custom promotion rule
      description: Retrieve a custom promotion rule
      tags:
      - custom_promotion_rules
      parameters:
      - name: customPromotionRuleId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '200':
          description: The custom promotion rule object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/customPromotionRuleResponse'
    patch:
      operationId: PATCH/custom_promotion_rules/customPromotionRuleId
      summary: Update a custom promotion rule
      description: Update a custom promotion rule
      tags:
      - custom_promotion_rules
      parameters:
      - name: customPromotionRuleId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/customPromotionRuleUpdate'
      responses:
        '200':
          description: The updated custom promotion rule object
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/customPromotionRuleResponse'
    delete:
      operationId: DELETE/custom_promotion_rules/customPromotionRuleId
      summary: Delete a custom promotion rule
      description: Delete a custom promotion rule
      tags:
      - custom_promotion_rules
      parameters:
      - name: customPromotionRuleId
        in: path
        schema:
          type: string
        required: true
        description: The resource's id
      responses:
        '204':
          description: No content
components:
  schemas:
    customPromotionRuleResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            type:
              type: string
              description: The resource's type
              enum:
              - custom_promotion_rules
            links:
              type: object
              properties:
                self:
                  type: string
                  description: URL
            attributes:
              $ref: '#/components/schemas/customPromotionRule/properties/data/properties/attributes'
            relationships:
              type: object
              properties:
                promotion:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - promotion
                        id:
                          type: string
                          description: The resource ID
                event_stores:
                  type: object
                  properties:
                    links:
                      type: object
                      properties:
                        self:
                          type: string
                          description: URL
                        related:
                          type: string
                          description: URL
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: The resource ID
    freeGiftPromotion:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - free_gift_promotions
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The promotion's internal name.
                  example: Personal promotion
                  nullable: false
                type:
                  type: string
                  description: The promotion's type.
                  example: percentage_discount_promotions
                  nullable: false
                  enum:
                  - percentage_discount_promotions
                  - free_shipping_promotions
                  - buy_x_pay_y_promotions
                  - free_gift_promotions
                  - fixed_price_promotions
                  - external_promotions
                  - fixed_amount_promotions
                  - flex_promotions
                currency_code:
                  type: string
                  description: The international 3-letter currency code as defined by the ISO 4217 standard.
                  example: EUR
                  nullable: true
                exclusive:
                  type: boolean
                  description: Indicates if the promotion will be applied exclusively, based on its priority score.
                  example: true
                  nullable: true
                priority:
                  type: integer
                  description: The priority assigned to the promotion (lower means higher priority).
                  example: 2
                  nullable: true
                starts_at:
                  type: string
                  description: The activation date/time of this promotion.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                expires_at:
                  type: string
                  description: The expiration date/time of this promotion (must be after starts_at).
                  example: '2018-01-02T12:00:00.000Z'
                  nullable: false
                total_usage_limit:
                  type: integer
                  description: The total number of times this promotion can be applied. When 'null' it means promotion can be applied infinite times.
                  example: 5
                  nullable: true
                total_usage_count:
                  type: integer
                  description: The number of times this promotion has been applied.
                  example: 2
                  nullable: true
                total_usage_reached:
                  type: boolean
                  description: Indicates if the promotion has been applied the total number of allowed times.
                  example: false
                  nullable: true
                active:
                  type: boolean
                  description: Indicates if the promotion is active (enabled and not expired).
                  example: true
                  nullable: true
                status:
                  type: string
                  description: The promotion status. One of 'disabled', 'expired', 'pending', 'active', or 'inactive'.
                  example: pending
                  nullable: true
                  enum:
                  - disabled
                  - expired
                  - pending
                  - active
                  - inactive
                weight:
                  type: integer
                  description: The weight of the promotion, computed by exclusivity, priority, type and start time. Determines the order of application, higher weight apply first.
                  example: 112
                  nullable: true
                coupons_count:
                  type: integer
                  description: The total number of coupons created for this promotion.
                  example: 2
                  nullable: true
                disabled_at:
                  type: string
                  description: Time at which this resource was disabled.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: true
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                max_quantity:
                  type: integer
                  description: The max quantity of free gifts globally applicable by the promotion.
                  example: 3
                  nullable: true
            relationships:
              type: object
              properties:
                market:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - markets
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                promotion_rules:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                order_amount_promotion_rule:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - order_amount_promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                sku_list_promotion_rule:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - sku_list_promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                coupon_codes_promotion_rule:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - coupon_codes_promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                custom_promotion_rule:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - custom_promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                sku_list:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - sku_lists
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                coupons:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - coupons
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                attachments:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - attachments
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                events:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - events
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                tags:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - tags
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                event_stores:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - event_stores
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                skus:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - skus
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    customPromotionRuleUpdate:
      required:
      - data
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - id
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - custom_promotion_rules
            id:
              type: string
              description: Unique identifier for the resource (hash).
              example: XAyRWNUzyN
            attributes:
              type: object
              properties:
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                filters:
                  type: object
                  description: The filters used to trigger promotion on the matching order and its relationships attributes.
                  example:
                    status_eq: pending
                    line_items_sku_code_eq: AAA
                  nullable: true
            relationships:
              type: object
              properties:
                promotion:
                  required:
                  - data
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - percentage_discount_promotions
                          - free_shipping_promotions
                          - buy_x_pay_y_promotions
                          - free_gift_promotions
                          - fixed_price_promotions
                          - external_promotions
                          - fixed_amount_promotions
                          - flex_promotions
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                  oneOf:
                  - $ref: '#/components/schemas/percentageDiscountPromotion'
                  - $ref: '#/components/schemas/freeShippingPromotion'
                  - $ref: '#/components/schemas/buyXPayYPromotion'
                  - $ref: '#/components/schemas/freeGiftPromotion'
                  - $ref: '#/components/schemas/fixedPricePromotion'
                  - $ref: '#/components/schemas/externalPromotion'
                  - $ref: '#/components/schemas/fixedAmountPromotion'
                  - $ref: '#/components/schemas/flexPromotion'
    externalPromotion:
      type: object
      properties:
        data:
          type: object
          required:
          - type
          - attributes
          properties:
            type:
              type: string
              description: The resource's type
              enum:
              - external_promotions
            attributes:
              type: object
              properties:
                name:
                  type: string
                  description: The promotion's internal name.
                  example: Personal promotion
                  nullable: false
                type:
                  type: string
                  description: The promotion's type.
                  example: percentage_discount_promotions
                  nullable: false
                  enum:
                  - percentage_discount_promotions
                  - free_shipping_promotions
                  - buy_x_pay_y_promotions
                  - free_gift_promotions
                  - fixed_price_promotions
                  - external_promotions
                  - fixed_amount_promotions
                  - flex_promotions
                currency_code:
                  type: string
                  description: The international 3-letter currency code as defined by the ISO 4217 standard.
                  example: EUR
                  nullable: true
                exclusive:
                  type: boolean
                  description: Indicates if the promotion will be applied exclusively, based on its priority score.
                  example: true
                  nullable: true
                priority:
                  type: integer
                  description: The priority assigned to the promotion (lower means higher priority).
                  example: 2
                  nullable: true
                starts_at:
                  type: string
                  description: The activation date/time of this promotion.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                expires_at:
                  type: string
                  description: The expiration date/time of this promotion (must be after starts_at).
                  example: '2018-01-02T12:00:00.000Z'
                  nullable: false
                total_usage_limit:
                  type: integer
                  description: The total number of times this promotion can be applied. When 'null' it means promotion can be applied infinite times.
                  example: 5
                  nullable: true
                total_usage_count:
                  type: integer
                  description: The number of times this promotion has been applied.
                  example: 2
                  nullable: true
                total_usage_reached:
                  type: boolean
                  description: Indicates if the promotion has been applied the total number of allowed times.
                  example: false
                  nullable: true
                active:
                  type: boolean
                  description: Indicates if the promotion is active (enabled and not expired).
                  example: true
                  nullable: true
                status:
                  type: string
                  description: The promotion status. One of 'disabled', 'expired', 'pending', 'active', or 'inactive'.
                  example: pending
                  nullable: true
                  enum:
                  - disabled
                  - expired
                  - pending
                  - active
                  - inactive
                weight:
                  type: integer
                  description: The weight of the promotion, computed by exclusivity, priority, type and start time. Determines the order of application, higher weight apply first.
                  example: 112
                  nullable: true
                coupons_count:
                  type: integer
                  description: The total number of coupons created for this promotion.
                  example: 2
                  nullable: true
                disabled_at:
                  type: string
                  description: Time at which this resource was disabled.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: true
                created_at:
                  type: string
                  description: Time at which the resource was created.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                updated_at:
                  type: string
                  description: Time at which the resource was last updated.
                  example: '2018-01-01T12:00:00.000Z'
                  nullable: false
                reference:
                  type: string
                  description: A string that you can use to add any external identifier to the resource. This can be useful for integrating the resource to an external system, like an ERP, a marketing tool, a CRM, or whatever.
                  example: ANY-EXTERNAL-REFEFERNCE
                  nullable: true
                reference_origin:
                  type: string
                  description: Any identifier of the third party system that defines the reference code.
                  example: ANY-EXTERNAL-REFEFERNCE-ORIGIN
                  nullable: true
                metadata:
                  type: object
                  description: Set of key-value pairs that you can attach to the resource. This can be useful for storing additional information about the resource in a structured format.
                  example:
                    foo: bar
                  nullable: true
                circuit_state:
                  type: string
                  description: The circuit breaker state, by default it is 'closed'. It can become 'open' once the number of consecutive failures overlaps the specified threshold, in such case no further calls to the failing callback are made.
                  example: closed
                  nullable: true
                circuit_failure_count:
                  type: integer
                  description: The number of consecutive failures recorded by the circuit breaker associated to this resource, will be reset on first successful call to callback.
                  example: 5
                  nullable: true
                shared_secret:
                  type: string
                  description: The shared secret used to sign the external request payload.
                  example: 1c0994cc4e996e8c6ee56a2198f66f3c
                  nullable: false
                external_includes:
                  type: array
                  description: List of related resources that will be included in the request to the external callback. Please do consult the documentation to check on which resource the includes are related (i.e. the order) and the defaults in case no list is provided.
                  example:
                  - order.line_item_options
                  nullable: true
                  items:
                    type: string
                promotion_url:
                  type: string
                  description: The URL to the service that will compute the discount.
                  example: https://external_promotion.yourbrand.com
                  nullable: false
            relationships:
              type: object
              properties:
                market:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - markets
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                promotion_rules:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
                order_amount_promotion_rule:
                  type: object
                  properties:
                    data:
                      type: object
                      properties:
                        type:
                          type: string
                          description: The resource's type
                          enum:
                          - order_amount_promotion_rules
                        id:
                          type: string
                          description: Unique identifier for the resource (hash).
                          example: XAyRWNUzyN
    

# --- truncated at 32 KB (122 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/commerce-layer/refs/heads/main/openapi/commerce-layer-custom-promotion-rules-api-openapi.yml