{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/recurly/json-schema/recurly-subscription-dto-schema.json",
  "title": "SubscriptionDto",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/recurly-commerce-openapi.yml#/components/schemas/SubscriptionDto",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "createdAt": {
      "format": "date-time",
      "type": "string"
    },
    "updatedAt": {
      "format": "date-time",
      "type": "string"
    },
    "friendlyId": {
      "type": "string"
    },
    "externalId": {
      "type": "string",
      "description": "The shopify contract ID of the subscription"
    },
    "subscriber": {
      "$ref": "#/$defs/SubscriberDto"
    },
    "purchaseDate": {
      "format": "date-time",
      "type": "string"
    },
    "trialEndsAt": {
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "cancelDate": {
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "cancelReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "pausedAtDate": {
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "pauseLimitSettings": {
      "type": [
        "object",
        "null"
      ]
    },
    "nextDeliveryDate": {
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "nextBillingDate": {
      "format": "date-time",
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "type": "string",
      "enum": [
        "ACTIVE",
        "PAUSED",
        "EXPIRED",
        "CANCELLED",
        "FAILED"
      ]
    },
    "deliveryCadenceCount": {
      "type": "number"
    },
    "deliveryCadenceUnit": {
      "type": "string",
      "enum": [
        "HOUR",
        "DAY",
        "MONTH",
        "WEEK",
        "YEAR"
      ]
    },
    "billingCadenceCount": {
      "type": "number"
    },
    "billingCadenceUnit": {
      "type": "string",
      "enum": [
        "HOUR",
        "DAY",
        "MONTH",
        "WEEK",
        "YEAR"
      ]
    },
    "isPrepaid": {
      "type": "boolean"
    },
    "isMembership": {
      "type": "boolean"
    },
    "currencyCode": {
      "type": "string"
    },
    "deliveryFirstName": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryLastName": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryAddress1": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryAddress2": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryCountry": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryProvince": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryCity": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryZip": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryShippingOption": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryPrice": {
      "type": [
        "number",
        "null"
      ]
    },
    "deliveryPhone": {
      "type": [
        "string",
        "null"
      ]
    },
    "deliveryCompany": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingFirstName": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingLastName": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingAddress1": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingAddress2": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingCountry": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingProvince": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingCity": {
      "type": [
        "string",
        "null"
      ]
    },
    "billingZip": {
      "type": [
        "string",
        "null"
      ]
    },
    "paymentMethodExternalId": {
      "type": "string",
      "description": "The shopify payment method card ID"
    },
    "paymentMethodType": {
      "type": "string",
      "description": "The payment method card type",
      "enum": [
        "CustomerCreditCard",
        "CustomerPaypalBillingAgreement",
        "CustomerShopPayAgreement"
      ],
      "default": "CustomerCreditCard"
    },
    "paymentMethodLast4Digits": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method last 4 digits"
    },
    "paymentMethodExpiryMonth": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method expiry month"
    },
    "paymentMethodExpiryYear": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method expiry year"
    },
    "paymentMethodBrand": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method card brand"
    },
    "paymentMethodEmail": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method email (only shows for paypal payment type)"
    },
    "paymentMethodName": {
      "type": [
        "string",
        "null"
      ],
      "description": "The payment method name"
    },
    "lines": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SubscriptionLineDto"
      }
    },
    "upcomingOrders": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UpcomingOrderDto"
      }
    },
    "customAttributes": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/CustomAttribute"
      }
    },
    "gift": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/$defs/SubscriptionGiftDto"
        }
      ]
    },
    "recipient": {
      "nullable": true,
      "description": "The gift recipient",
      "allOf": [
        {
          "$ref": "#/$defs/SubscriberDto"
        }
      ]
    },
    "discountCodes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/SubscriptionDiscountCodeDto"
      }
    },
    "dunningInstances": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/DunningInstanceDto"
      }
    }
  },
  "required": [
    "id",
    "createdAt",
    "updatedAt",
    "friendlyId",
    "externalId",
    "subscriber",
    "purchaseDate",
    "trialEndsAt",
    "cancelDate",
    "cancelReason",
    "pausedAtDate",
    "pauseLimitSettings",
    "nextDeliveryDate",
    "nextBillingDate",
    "status",
    "deliveryCadenceCount",
    "deliveryCadenceUnit",
    "billingCadenceCount",
    "billingCadenceUnit",
    "isPrepaid",
    "isMembership",
    "currencyCode",
    "deliveryFirstName",
    "deliveryLastName",
    "deliveryAddress1",
    "deliveryAddress2",
    "deliveryCountry",
    "deliveryProvince",
    "deliveryCity",
    "deliveryZip",
    "deliveryShippingOption",
    "deliveryPrice",
    "deliveryPhone",
    "deliveryCompany",
    "billingFirstName",
    "billingLastName",
    "billingAddress1",
    "billingAddress2",
    "billingCountry",
    "billingProvince",
    "billingCity",
    "billingZip",
    "paymentMethodExternalId",
    "paymentMethodType",
    "paymentMethodLast4Digits",
    "paymentMethodExpiryMonth",
    "paymentMethodExpiryYear",
    "paymentMethodBrand",
    "paymentMethodEmail",
    "paymentMethodName",
    "lines",
    "upcomingOrders",
    "customAttributes",
    "gift",
    "recipient",
    "discountCodes",
    "dunningInstances"
  ],
  "$defs": {
    "BundleItemDto": {
      "type": "object",
      "properties": {
        "variant": {
          "nullable": true,
          "allOf": [
            {
              "$ref": "#/$defs/VariantDto"
            }
          ]
        },
        "quantity": {
          "type": "number"
        },
        "currentPrice": {
          "type": "number"
        }
      },
      "required": [
        "variant",
        "quantity",
        "currentPrice"
      ]
    },
    "CustomAttribute": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        },
        "value": {
          "type": "string"
        }
      },
      "required": [
        "key",
        "value"
      ]
    },
    "DunningInstanceDto": {
      "type": "object",
      "properties": {
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "dunningComplete": {
          "type": "boolean"
        },
        "lastRetryDate": {
          "format": "date-time",
          "type": "string"
        },
        "billingRetryCount": {
          "type": "number"
        },
        "maxBillingRetryCount": {
          "type": "number"
        },
        "errorCode": {
          "type": "string"
        },
        "isReactivated": {
          "type": "boolean"
        },
        "contractCancelledAt": {
          "format": "date-time",
          "type": "string"
        },
        "maxBillingRetryCountAction": {
          "type": "string"
        }
      },
      "required": [
        "createdAt",
        "dunningComplete",
        "lastRetryDate",
        "billingRetryCount",
        "maxBillingRetryCount",
        "errorCode",
        "isReactivated",
        "contractCancelledAt",
        "maxBillingRetryCountAction"
      ]
    },
    "OneTimeAddOnDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "variantId": {
          "type": "string"
        },
        "quantity": {
          "type": "number"
        },
        "modifierType": {
          "type": "string",
          "enum": [
            "PERCENTAGE",
            "AMOUNT",
            "FIXED_AMOUNT"
          ]
        },
        "discount": {
          "type": "number"
        },
        "variantPriceOverride": {
          "type": "number"
        },
        "discountedVariantPrice": {
          "type": "number",
          "description": "Calculated price after applying discount"
        }
      },
      "required": [
        "id",
        "variantId",
        "quantity"
      ]
    },
    "ProductForVariantDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify product ID"
        },
        "imageUrl": {
          "type": [
            "string",
            "null"
          ]
        },
        "productTitle": {
          "type": [
            "string",
            "null"
          ]
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "externalId",
        "imageUrl",
        "productTitle",
        "description"
      ]
    },
    "SubscriberDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string",
          "description": "The date the shopper record was created in the Commerce system. This is merchant-agnostic and may predate when the shopper first subscribed to your store."
        },
        "relationshipStartedAt": {
          "format": "date-time",
          "type": [
            "string",
            "null"
          ],
          "description": "The date the relationship between this shopper and your store began (e.g. their first subscription). Null if unknown, e.g. gift recipients without a direct relationship."
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify id of the subscriber"
        },
        "firstName": {
          "type": [
            "string",
            "null"
          ]
        },
        "lastName": {
          "type": [
            "string",
            "null"
          ]
        },
        "email": {
          "type": "string"
        },
        "phoneCountryCode": {
          "type": [
            "string",
            "null"
          ]
        },
        "phone": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "createdAt",
        "relationshipStartedAt",
        "updatedAt",
        "externalId",
        "firstName",
        "lastName",
        "email",
        "phoneCountryCode",
        "phone"
      ]
    },
    "SubscriptionDiscountCodeDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "deletedAt": {
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        },
        "subscriptionId": {
          "type": "string",
          "description": "The id of the subscription"
        },
        "code": {
          "type": "string",
          "description": "The discount code"
        },
        "discountCodeExternalId": {
          "type": "string",
          "description": "The shopify id of the discount code"
        },
        "type": {
          "type": "string",
          "enum": [
            "MANUAL",
            "CODE_DISCOUNT",
            "AUTOMATIC_DISCOUNT"
          ]
        },
        "targetType": {
          "type": "string",
          "enum": [
            "SHIPPING_LINE",
            "LINE_ITEM"
          ]
        },
        "discountModifier": {
          "type": "string",
          "enum": [
            "PERCENTAGE",
            "FIXED_AMOUNT"
          ]
        },
        "discount": {
          "type": "number"
        },
        "recurringCycleLimit": {
          "type": "number"
        },
        "usageCount": {
          "type": "number"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "deletedAt",
        "subscriptionId",
        "code",
        "discountCodeExternalId",
        "type",
        "targetType",
        "discountModifier",
        "discount",
        "usageCount"
      ]
    },
    "SubscriptionGiftDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "numberOfDeliveries": {
          "type": "number"
        },
        "to": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "isOpened": {
          "type": "boolean"
        },
        "isPrepaid": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "numberOfDeliveries",
        "to",
        "email",
        "message",
        "isOpened",
        "isPrepaid"
      ]
    },
    "SubscriptionLineDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify contract line ID"
        },
        "subscriptionId": {
          "type": "string"
        },
        "variant": {
          "$ref": "#/$defs/VariantDto"
        },
        "quantity": {
          "type": "number"
        },
        "currentPrice": {
          "type": "number"
        },
        "subscriptionOfferOptionId": {
          "type": [
            "string",
            "null"
          ]
        },
        "sellingPlanId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The shopify selling plan ID of the subscription offer option"
        },
        "productFulfillmentTypeRestriction": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "PHYSICAL_ONLY",
            "DIGITAL_ONLY"
          ],
          "description": "Fulfillment type restriction declared on the subscription offer, if any"
        },
        "schedule": {
          "nullable": true,
          "allOf": [
            {
              "$ref": "#/$defs/SubscriptionLineScheduleDto"
            }
          ]
        },
        "customAttributes": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/CustomAttribute"
          }
        },
        "bundleItems": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/BundleItemDto"
          }
        },
        "deletedAt": {
          "format": "date-time",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "externalId",
        "subscriptionId",
        "variant",
        "quantity",
        "currentPrice",
        "subscriptionOfferOptionId",
        "sellingPlanId",
        "productFulfillmentTypeRestriction",
        "schedule",
        "customAttributes"
      ]
    },
    "SubscriptionLineScheduleDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "deliveryInterval": {
          "type": "number",
          "description": "The frequency multiplier that determines how often an add-on product is included with deliveries. Values: 1 (every delivery), 2 (every other delivery), 3 (every third delivery), etc"
        },
        "deliveryStartOffset": {
          "type": "number",
          "description": "How many orders to skip before starting the delivery cadence"
        },
        "lastIncludedOrderNumber": {
          "type": "number"
        },
        "lastIncludedDate": {
          "format": "date-time",
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        }
      },
      "required": [
        "id",
        "deliveryInterval",
        "deliveryStartOffset",
        "lastIncludedOrderNumber",
        "lastIncludedDate",
        "createdAt",
        "updatedAt"
      ]
    },
    "SubscriptionOfferDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify selling plan group ID"
        },
        "type": {
          "type": "string",
          "enum": [
            "ONETIME_AND_SUBSCRIPTION",
            "ONE_TIME_AND_PREPAID_SUBSCRIPTION",
            "SUBSCRIPTION_ONLY",
            "PREPAID_SUBSCRIPTION_ONLY",
            "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
            "SUBSCRIPTION_AND_PREPAID",
            "MEMBERSHIP"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "ARCHIVED",
            "DRAFT"
          ]
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "subscriptionOfferOptions": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SubscriptionOfferOptionDto"
          }
        },
        "cancellationFlowId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ID of the associated cancellation flow, if any"
        },
        "trialDurationValue": {
          "type": [
            "number",
            "null"
          ]
        },
        "trialDurationUnit": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "DAYS",
            "WEEKS",
            "MONTHS",
            "YEARS"
          ]
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "externalId",
        "type",
        "status",
        "name",
        "description",
        "subscriptionOfferOptions",
        "trialDurationValue",
        "trialDurationUnit"
      ]
    },
    "SubscriptionOfferOptionDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "createdAt": {
          "format": "date-time",
          "type": "string"
        },
        "updatedAt": {
          "format": "date-time",
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify selling plan ID"
        },
        "type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "ONETIME_AND_SUBSCRIPTION",
            "ONE_TIME_AND_PREPAID_SUBSCRIPTION",
            "SUBSCRIPTION_ONLY",
            "PREPAID_SUBSCRIPTION_ONLY",
            "ONETIME_AND_SUBSCRIPTION_AND_PREPAID",
            "SUBSCRIPTION_AND_PREPAID",
            "MEMBERSHIP"
          ]
        },
        "name": {
          "type": "string"
        },
        "deliveryCadenceCount": {
          "type": "number"
        },
        "deliveryCadenceUnit": {
          "type": "string",
          "enum": [
            "HOUR",
            "DAY",
            "MONTH",
            "WEEK",
            "YEAR"
          ]
        },
        "billingCadenceCount": {
          "type": "number"
        },
        "billingCadenceUnit": {
          "type": "string",
          "enum": [
            "HOUR",
            "DAY",
            "MONTH",
            "WEEK",
            "YEAR"
          ]
        },
        "discount": {
          "type": "number"
        },
        "discountModifier": {
          "type": "string",
          "enum": [
            "PERCENTAGE",
            "AMOUNT",
            "FIXED_AMOUNT"
          ]
        },
        "archived": {
          "type": "boolean"
        }
      },
      "required": [
        "id",
        "createdAt",
        "updatedAt",
        "externalId",
        "type",
        "name",
        "deliveryCadenceCount",
        "deliveryCadenceUnit",
        "billingCadenceCount",
        "billingCadenceUnit",
        "discount",
        "discountModifier",
        "archived"
      ]
    },
    "UpcomingOrderDto": {
      "type": "object",
      "properties": {
        "scheduledDate": {
          "format": "date-time",
          "type": "string"
        },
        "isSkipped": {
          "type": "boolean"
        },
        "lines": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/SubscriptionLineDto"
          }
        },
        "oneTimeAddOns": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/OneTimeAddOnDto"
          }
        }
      },
      "required": [
        "scheduledDate",
        "isSkipped",
        "lines",
        "oneTimeAddOns"
      ]
    },
    "VariantDto": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "externalId": {
          "type": "string",
          "description": "The shopify variant ID"
        },
        "status": {
          "type": "string",
          "enum": [
            "ACTIVE",
            "DELETED"
          ]
        },
        "currentPrice": {
          "type": "number"
        },
        "variantTitle": {
          "type": "string"
        },
        "sku": {
          "type": [
            "string",
            "null"
          ]
        },
        "requiresShipping": {
          "type": "boolean"
        },
        "product": {
          "nullable": true,
          "allOf": [
            {
              "$ref": "#/$defs/ProductForVariantDto"
            }
          ]
        },
        "subscriptionOffer": {
          "$ref": "#/$defs/SubscriptionOfferDto"
        }
      },
      "required": [
        "id",
        "externalId",
        "status",
        "currentPrice",
        "variantTitle",
        "sku",
        "requiresShipping"
      ]
    }
  }
}