Promotions Import Format

This section describes how to provide promotion data to the import service.

{
  "$ref": "#/definitions/promotionSchema",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "definitions": {
    "promotionSchema": {
      "type": "object",
      "properties": {
        "promotions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "type": {
                "type": "string",
                "enum": ["PROMOTION"],
                "description": "The type of the resource, in this case, it's always PROMOTION"
              },
              "enabled": {
                "type": "boolean",
                "description": "Whether the promotion is enabled to consume"
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "description": "The name of the promotion"
              },
              "description": {
                "type": "string",
                "description": "A detailed description of the promotion"
              },
              "createdAt": {
                "type": "string",
                "format": "date-time",
                "description": "The date and time the promotion was created"
              },
              "updatedAt": {
                "type": "string",
                "format": "date-time",
                "description": "The date and time the promotion was last updated"
              },
              "code": {
                "type": "string",
                "minLength": 1,
                "maxLength": 30,
                "description": "The unique code to redeem the promotion"
              },
              "constraint": {
                "type": "object",
                "properties": {
                  "promoStartAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The date and time the promotion starts (inclusive)"
                  },
                  "promoEndAt": {
                    "type": "string",
                    "format": "date-time",
                    "description": "The date and time the promotion ends (inclusive)"
                  },
                  "maxUsage": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "The maximum number of times the promotion can be redeemed"
                  },
                  "usageCount": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "The number of times the promotion has been redeemed"
                  },
                  "subscription": {
                    "type": "object",
                    "properties": {
                      "newOnly": {
                        "type": "boolean",
                        "description": "Whether the promotion is only for new subscriptions"
                      },
                      "typeIds": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "The list of subscription type IDs that the promotion can be consumed. This is optional"
                      }
                    },
                    "required": ["newOnly"],
                    "additionalProperties": false,
                    "description": "The subscription contract constraint of the promotion. This is optional"
                  }
                },
                "required": ["promoStartAt", "promoEndAt", "maxUsage", "usageCount", "subscription"],
                "additionalProperties": false
              },
              "rules": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "effect": {
                      "type": "object",
                      "properties": {
                        "effectType": {
                          "type": "string",
                          "enum": ["PERCENTAGE_DISCOUNT", "AMOUNT_DISCOUNT"],
                          "description": "The type of the effect"
                        },
                        "amount": {
                          "type": "integer",
                          "minimum": 0,
                          "description": "The value amount of the effect"
                        }
                      },
                      "required": ["effectType", "amount"],
                      "additionalProperties": false
                    },
                    "conditions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "conditionType": {
                            "type": "string",
                            "enum": ["ORDER_NUMBER_AFTER_APPLIED", "SUBSCRIPTION_CONTRACT_ORDER_NUMBER"],
                            "description": "The type of the condition"
                          },
                          "value": {
                            "anyOf": [
                              {
                                "type": "integer",
                                "minimum": 1
                              },
                              {
                                "type": "array",
                                "items": {
                                  "type": "integer",
                                  "minimum": 1
                                }
                              }
                            ],
                            "description": "The value of the condition type"
                          }
                        },
                        "required": ["conditionType", "value"],
                        "additionalProperties": false
                      },
                      "description": "The conditions to determine if an order is qualified to the effect"
                    }
                  },
                  "required": ["effect", "conditions"],
                  "additionalProperties": false
                },
                "description": "The list of rules that the promotion applies to the subscription or order"
              }
            },
            "required": ["type", "enabled", "name", "description", "createdAt", "updatedAt", "code", "rules"],
            "additionalProperties": false
          },
          "description": "A list of promotions that can be consumed by subscriptions or orders"
        }
      },
      "required": ["promotions"],
      "additionalProperties": false
    }
  }
}

Field descriptions

• promotions - A list of promotions that can be consumed by subscriptions or orders.

• type - The type of the resource, in this case, it's always PROMOTION.

• enabled - Whether the promotion is enabled to consume.

• name - The name of the promotion.

• description - A detailed description of the promotion.

• createdAt - The date and time the promotion was created.

• updatedAt - The date and time the promotion was last updated.

• code - The unique code to redeem the promotion.

• constraint - Constraints related to the promotion:

  • promoStartAt - The date and time the promotion starts (inclusive).

  • promoEndAt - The date and time the promotion ends (inclusive).

  • maxUsage - The maximum number of times the promotion can be redeemed.

  • usageCount - The number of times the promotion has been redeemed.

  • subscription - The subscription contract constraint of the promotion. This is optional:

    • newOnly - Whether the promotion is only for new subscriptions.

    • typeIds - The list of subscription type IDs that the promotion can be consumed. This is optional.

• rules - The list of rules that the promotion applies to the subscription or order (can have both a percentage discount rule and an amount rule):

  • effect: The effect of the promotion:

    • effectType - The type of the effect, it's either PERCENTAGE_DISCOUNT or AMOUNT_DISCOUNT.

    • amount - The amount value of the effect.

  • conditions: A list of conditions to determine if an order is qualified to the effect (currently requires a condition per order the condition is applied to):

    • conditionType - The type of the condition.

    • value - The value of the condition type, an integer representing either the number of orders from the point the promo is applied, or just the order number. This can also be provided as an array of integers as a simplification compared to creating one condition per order.

Example

{
  "promotions": [
    {
      "type": "PROMOTION",
      "enabled": true,
      "name": "Glug Demo",
      "description": "Glug Demo Campaign",
      "createdAt": "2023-12-19T17:09:35Z",
      "updatedAt": "2024-01-25T11:34:15Z",
      "code": "GLUG_TEST",
      "constraint": {
        "promoStartAt": "2023-12-19T00:00:00Z",
        "promoEndAt": "2024-04-30T00:00:00Z",
        "maxUsage": 1000,
        "usageCount": 0,
        "subscription": {
          "newOnly": true
        }
      },
      "rules": [
        {
          "effect": {
            "effectType": "AMOUNT_DISCOUNT",
            "amount": 20
          },
          "conditions": [
            {
              "conditionType": "SUBSCRIPTION_CONTRACT_ORDER_NUMBER",
              "value": 1
            }
          ]
        },
        {
          "effect": {
            "effectType": "PERCENTAGE_DISCOUNT",
            "amount": 15
          },
          "conditions": [
            {
              "conditionType": "SUBSCRIPTION_CONTRACT_ORDER_NUMBER",
              "value": [1, 2, 3]
            }
          ]
        }
      ]
    }
  ]
}