{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/elastic-path/main/json-schema/subscriptions.json", "title": "Subscriptions Introduction", "description": "Elastic Path Subscriptions allows you to offer your customers subscriptions and recurring billing for your plans and services. Elastic Path Subscriptions gives you the flexibility to pause, update, or reactivate your subscription offerings, change subscription cycles and apply discounts.", "version": "26.0427.7514362", "$defs": { "ActivePricingOption": { "type": "boolean", "description": "Whether a pricing option is active on a subscription using that offering. The `active_pricing_option` attribute is null if a pricing option is not active in a subscription.", "example": true }, "ActivePlan": { "type": "boolean", "description": "Whether a plan is active on a subscription using that offering. The `active_plan` attribute is null if a plan is not active in a subscription.", "example": true }, "ExternalRef": { "description": "A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.", "type": "string", "example": "abc123", "maxLength": 2048 }, "ExternalRefUpdate": { "description": "A unique attribute that you could use to contain information from another company system, for example. The maximum length is 2048 characters.", "type": "string", "example": "abc123", "maxLength": 2048, "nullable": true }, "SubscriptionType": { "type": "string", "example": "subscription", "enum": [ "subscription" ] }, "ProrationPolicyType": { "type": "string", "example": "subscription_proration_policy", "enum": [ "subscription_proration_policy" ] }, "SubscriptionDunningRuleType": { "type": "string", "example": "subscription_dunning_rule", "enum": [ "subscription_dunning_rule" ] }, "SubscriptionFeatureType": { "type": "string", "example": "subscription_feature", "enum": [ "subscription_feature" ] }, "SubscriptionOfferingType": { "type": "string", "example": "subscription_offering", "enum": [ "subscription_offering" ] }, "SubscriptionOfferingFeatureType": { "type": "string", "example": "subscription_offering_feature", "enum": [ "subscription_offering_feature" ] }, "SubscriptionOfferingPlanType": { "type": "string", "example": "subscription_offering_plan", "enum": [ "subscription_offering_plan" ] }, "SubscriptionOfferingPricingOptionType": { "type": "string", "example": "subscription_offering_pricing_option", "enum": [ "subscription_offering_pricing_option" ] }, "SubscriptionJobType": { "type": "string", "example": "subscription_job", "enum": [ "subscription_job" ] }, "SubscriptionImportType": { "type": "string", "example": "subscription_import", "enum": [ "subscription_import" ] }, "SubscriptionImportErrorType": { "type": "string", "example": "subscription_import_error", "enum": [ "subscription_import_error" ] }, "SubscriptionImportError": { "type": "object", "required": [ "id", "type", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionImportErrorType" }, "meta": { "$ref": "#/components/schemas/SubscriptionImportErrorMeta" } } }, "SubscriptionImportErrorMeta": { "type": "object", "required": [ "owner", "timestamps", "error", "field", "line_number" ], "properties": { "owner": { "type": "string", "example": "store" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" }, "error": { "type": "string", "example": "offering name cannot be empty" }, "field": { "type": "string", "example": "name" }, "line_number": { "type": "integer", "description": "The line in the imported JSONL file at which the validation error occurred. Starts from 1.", "example": 123 }, "external_ref": { "$ref": "#/components/schemas/ExternalRef" } } }, "SubscriptionInvoiceType": { "description": "This represents the type of resource object being returned. Always `subscription_invoice`.", "type": "string", "example": "subscription_invoice", "enum": [ "subscription_invoice" ] }, "SubscriptionInvoicePaymentType": { "type": "string", "description": "This represents the type of resource object being returned. Always `subscription_invoice_payment`.", "example": "subscription_invoice_payment", "enum": [ "subscription_invoice_payment" ] }, "SubscriptionInvoicePaymentRefundType": { "type": "string", "description": "This represents the type of resource object being returned. Always `subscription_invoice_payment_refund`.", "example": "subscription_invoice_payment_refund", "enum": [ "subscription_invoice_payment_refund" ] }, "Links": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Link" } }, "Link": { "anyOf": [ { "$ref": "#/components/schemas/LinkURI" }, { "$ref": "#/components/schemas/LinkObject" } ] }, "LinkURI": { "type": "string", "format": "uri", "example": "http://example.com/articles/1/comments", "nullable": true }, "LinkObject": { "type": "object", "properties": { "href": { "type": "string", "format": "uri", "example": "http://example.com/articles/1/comments" }, "title": { "type": "string", "example": "Comments" }, "describedby": { "type": "string", "format": "uri", "example": "http://example.com/schemas/article-comments" } } }, "Timestamps": { "required": [ "created_at", "updated_at" ], "properties": { "updated_at": { "description": "The date and time a resource was updated.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "created_at": { "description": "The date and time a resource was created.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "Status": { "type": "string", "description": "The status of a subscription, either `active` or `inactive`.", "example": "active", "enum": [ "active", "inactive" ], "x-go-type": "model.SubscriptionStatus", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "RelationshipsRequest": { "description": "Enumerates a list of resources that are related.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipData" } } } }, "Relationships": { "description": "Relationships are established between different subscription entities. For example, a plan and a pricing option are related to an offering, as both are attached to it.", "additionalProperties": { "$ref": "#/components/schemas/Relationship" }, "example": { "pricing-options": { "links": { "related": "/offerings/:offering-id/pricing-options", "self": "/offerings/:offering-id" }, "data": { "type": "offering-pricing-option", "id": "625fe958-7b4b-40a0-a2c0-dbb8f31eec0d" } } } }, "Relationship": { "anyOf": [ { "$ref": "#/components/schemas/SingleRelationship" }, { "$ref": "#/components/schemas/ManyRelationship" } ] }, "ManyRelationship": { "description": "The list of resources that are related.", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipData" } }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "SingleRelationship": { "description": "The subscription resource that is related.", "properties": { "data": { "$ref": "#/components/schemas/RelationshipData" }, "links": { "$ref": "#/components/schemas/RelationshipLinks" } } }, "RelationshipData": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "type": "string", "description": "This represents the type of resource being returned.", "example": "11111111-2222-3333-4444-555555555555" } } }, "RelationshipLinks": { "description": "Links are used to allow you, as an API consumer, to move between requests. Single entities use a self parameter with a link to that specific resource. Sometimes, there aren\u2019t enough entities for a project to fill multiple pages. In this situation, we return some defaults, instead of expecting you to", "type": "object", "properties": { "related": { "type": "string", "example": "foo.bar" } } }, "TimePeriod": { "description": "A period of time between a start and end point.", "required": [ "start", "end" ], "properties": { "start": { "description": "The date and time a billing period started.", "type": "string", "format": "date-time", "example": "2017-07-21T17:32:28Z" }, "end": { "description": "The date and time a billing period ended.", "type": "string", "format": "date-time", "example": "2017-07-21T17:32:28Z" } } }, "SingleCurrencyPrice": { "description": "A price in a single currency.", "required": [ "amount", "currency" ], "properties": { "currency": { "type": "string", "description": "The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price.", "example": "USD", "maxLength": 1024 }, "amount": { "type": "integer", "format": "int64", "description": "The value as a whole number of the currency's smallest subdivision.", "example": 100 }, "includes_tax": { "type": "boolean", "description": "Whether the amount includes any taxes.", "example": true } }, "example": { "currency": "USD", "amount": 100, "includes_tax": false } }, "PriceUnits": { "type": "object", "description": "The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans th", "required": [ "unit", "amount" ], "properties": { "unit": { "type": "string", "description": "A unit of time.", "enum": [ "day", "month" ], "example": "day", "x-go-type": "model.PriceUnitsUnit", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "amount": { "type": "integer", "description": "The number of days or months the period covers.", "example": 7, "minimum": 1 } } }, "NullablePriceUnits": { "type": "object", "nullable": true, "description": "The timeframe during which the plan price is applicable. For example, for a streaming service, the price is $12.99 and the `unit` is `months` and the `amount` is `1`. In other words, the streaming service is available for $12.99 a month. You may want to specify a unit price if you have many plans th", "required": [ "unit", "amount" ], "properties": { "unit": { "type": "string", "description": "A unit of time, either days or months.", "enum": [ "day", "month" ], "example": "day", "x-go-type": "model.PriceUnitsUnit", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "amount": { "type": "integer", "description": "The number of days or months the period covers.", "example": 7, "minimum": 1 } } }, "Price": { "additionalProperties": { "type": "object", "description": "The base price.", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "minimum": 0, "example": 100, "description": "The value as a whole number of the currency's smallest subdivision." }, "includes_tax": { "type": "boolean", "example": true, "description": "Indicates whether the amount includes any taxes." } } }, "example": { "USD": { "amount": 100, "includes_tax": false }, "GBP": { "amount": 90, "includes_tax": true } } }, "NullablePrice": { "type": "object", "additionalProperties": { "type": "object", "required": [ "amount" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 100, "description": "The value as a whole number of the currency's smallest subdivision." }, "includes_tax": { "type": "boolean", "example": true, "description": "Whether the amount includes any taxes." } }, "nullable": true }, "example": { "USD": { "amount": 100, "includes_tax": false }, "GBP": { "amount": 90, "includes_tax": true } }, "nullable": true }, "OfferingPlanPrices": { "type": "object", "description": "A list of plan prices for each of its pricing options.", "additionalProperties": { "$ref": "#/components/schemas/OfferingPlanPriceForPricingOption" } }, "OfferingPlanPriceForPricingOption": { "properties": { "price": { "$ref": "#/components/schemas/Price" }, "display_price": { "$ref": "#/components/schemas/DisplayPrice" } } }, "DisplayPrice": { "properties": { "without_tax": { "$ref": "#/components/schemas/PriceFormatting" }, "with_tax": { "$ref": "#/components/schemas/PriceFormatting" }, "tax": { "description": "Tax component when itemized (for example on subscription invoices). Omitted for catalog prices\nthat only expose with/without tax.\n", "$ref": "#/components/schemas/PriceFormatting" } }, "example": { "without_tax": { "amount": 100, "currency": "USD", "formatted": "$1.00" }, "with_tax": { "amount": 110, "currency": "USD", "formatted": "$1.10" }, "tax": { "amount": 10, "currency": "USD", "formatted": "$0.10" } } }, "PriceFormatting": { "required": [ "amount", "currency", "formatted" ], "properties": { "amount": { "type": "integer", "format": "int64", "example": 100, "description": "The unformatted amount for the objects." }, "currency": { "type": "string", "format": "string", "example": "USD", "description": "The three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html) in uppercase, associated with a price." }, "formatted": { "type": "string", "format": "string", "example": "$1.00", "description": "The formatted amount for the objects." } } }, "Feature": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureResponseAttributes" }, "meta": { "$ref": "#/components/schemas/FeatureMeta" } } }, "FeatureMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "FeatureCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureAttributes" } } }, "FeatureUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureUpdateAttributes" } } }, "OfferingFeatureCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionOfferingFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureAttributes" } } }, "FeatureResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/FeatureAttributes" } ] }, "FeatureTag": { "type": "string", "description": "A tag to add to the customer's account when entitled to the feature.", "minLength": 1, "maxLength": 64, "pattern": "^[0-9A-Za-z_-]+$", "example": "digital_library_access" }, "FeatureAccessAttributes": { "required": [ "type", "tag" ], "properties": { "type": { "type": "string", "enum": [ "access" ], "example": "access" }, "tag": { "$ref": "#/components/schemas/FeatureTag" } } }, "FeaturePromotion": { "required": [ "name", "tag" ], "properties": { "name": { "type": "string", "description": "The name of the feature.", "minLength": 3, "maxLength": 1024, "example": "Digital library access" }, "tag": { "$ref": "#/components/schemas/FeatureTag" }, "promotion_id": { "$ref": "#/components/schemas/UUID" } } }, "FeaturePromotionAttributes": { "required": [ "type", "promotions" ], "properties": { "type": { "type": "string", "enum": [ "promotion" ], "example": "promotion" }, "promotions": { "type": "array", "items": { "$ref": "#/components/schemas/FeaturePromotion" } } } }, "FeatureUsageAttributes": { "required": [ "type", "tag", "label", "default_value" ], "properties": { "type": { "type": "string", "enum": [ "usage" ], "example": "usage" }, "tag": { "$ref": "#/components/schemas/FeatureTag" }, "label": { "type": "string", "description": "The property that has a usage limit.", "minLength": 3, "maxLength": 1024, "example": "Digital downloads" }, "default_value": { "type": "integer", "description": "The default initial value", "example": 10 } } }, "FeatureConfiguration": { "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The type of feature, one of access, promotion or usage.", "enum": [ "access", "promotion", "usage" ], "example": "access", "x-go-type": "string" } }, "oneOf": [ { "$ref": "#/components/schemas/FeatureAccessAttributes" }, { "$ref": "#/components/schemas/FeaturePromotionAttributes" }, { "$ref": "#/components/schemas/FeatureUsageAttributes" } ], "discriminator": { "propertyName": "type", "mapping": { "access": "#/components/schemas/FeatureAccessAttributes", "promotion": "#/components/schemas/FeaturePromotionAttributes", "usage": "#/components/schemas/FeatureUsageAttributes" } } }, "FeatureAttributes": { "required": [ "name", "configuration" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "The name of the feature.", "minLength": 3, "maxLength": 1024, "example": "Digital library access" }, "description": { "type": "string", "description": "The feature description to display to customers.", "maxLength": 1024, "example": "Access to over 100 ebooks via the digital library." }, "configuration": { "$ref": "#/components/schemas/FeatureConfiguration" } } }, "FeatureUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "description": "The name of the feature.", "minLength": 3, "maxLength": 1024, "example": "Digital library access" }, "description": { "type": "string", "description": "The feature description to display to customers.", "maxLength": 1024, "example": "Access to over 100 ebooks via the digital library.", "nullable": true }, "configuration": { "$ref": "#/components/schemas/FeatureConfiguration" } } }, "PlanMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "prices": { "$ref": "#/components/schemas/OfferingPlanPrices" }, "display_price": { "$ref": "#/components/schemas/DisplayPrice" }, "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" }, "active_plan": { "$ref": "#/components/schemas/ActivePlan" } } }, "OfferingPlanCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionOfferingPlanType" }, "attributes": { "$ref": "#/components/schemas/OfferingPlanAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" } } }, "OfferingPlanAttributes": { "allOf": [ { "$ref": "#/components/schemas/PlanAttributes" }, { "$ref": "#/components/schemas/OfferingPlanExtraAttributes" } ] }, "OfferingPlanResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/PlanResponseAttributes" }, { "$ref": "#/components/schemas/OfferingPlanResponseExtraAttributes" } ] }, "OfferingPlanExtraAttributes": { "properties": { "feature_configurations": { "type": "object", "description": "A map of configurations indicating which features are available for the plan", "additionalProperties": { "$ref": "#/components/schemas/FeaturePlanConfiguration" } } } }, "OfferingPlanResponseExtraAttributes": { "required": [ "feature_configurations" ], "properties": { "feature_configurations": { "type": "object", "description": "A map of configurations indicating which features are available for the plan", "additionalProperties": { "$ref": "#/components/schemas/FeaturePlanConfiguration" } } } }, "PlanResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/PlanAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "PlanAttributes": { "required": [ "name" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "The name of the plan.", "minLength": 3, "maxLength": 1024, "example": "Magazine" }, "description": { "type": "string", "description": "The plan or service description to display to customers.", "maxLength": 1024, "example": "A lovely magazine that is published every month." }, "sku": { "type": "string", "description": "A stock keeping unit for the plan, if appropriate.", "maxLength": 1024, "example": "MAGAZINE1" }, "main_image": { "type": "string", "format": "uri", "description": "A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.", "maxLength": 1024, "example": "https://magazine.com/cover.jpg" }, "price": { "$ref": "#/components/schemas/Price" }, "price_units": { "$ref": "#/components/schemas/PriceUnits" } } }, "OfferingPlanUpdateAttributes": { "allOf": [ { "$ref": "#/components/schemas/PlanUpdateAttributes" }, { "$ref": "#/components/schemas/OfferingPlanUpdateExtraAttributes" } ] }, "OfferingPlanUpdateExtraAttributes": { "properties": { "feature_configurations": { "type": "object", "description": "A map of configurations indicating which features are available for the plan", "additionalProperties": { "$ref": "#/components/schemas/FeaturePlanConfigurationUpdate" } } } }, "PlanUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "description": "The name of the plan.", "minLength": 3, "maxLength": 1024, "example": "Magazine" }, "description": { "type": "string", "description": "The plan or service description to display to customers.", "maxLength": 1024, "example": "A lovely magazine that is published every month.", "nullable": true }, "sku": { "type": "string", "description": "A stock keeping unit for the plan, if appropriate.", "maxLength": 1024, "example": "MAGAZINE1", "nullable": true }, "main_image": { "type": "string", "format": "uri", "description": "A URL from which an image or file for the plan can be fetched. You can either upload your images and files to Commerce using the Commerce Files API or you can use your own content delivery network. If you are using the Commerce Files API, use [**Create a File**](/docs/api/pxm/files/create-a-file) to upload your file and return an HREF link in the response. An extensive range of [**media and file extensions**](/docs/api/pxm/files/files-service-api) are supported.", "maxLength": 1024, "example": "https://magazine.com/cover.jpg", "nullable": true }, "price": { "$ref": "#/components/schemas/NullablePrice" }, "price_units": { "$ref": "#/components/schemas/NullablePriceUnits" } } }, "DunningRule": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionDunningRuleType" }, "attributes": { "$ref": "#/components/schemas/DunningRuleAttributes" }, "meta": { "$ref": "#/components/schemas/DunningRuleMeta" } } }, "DunningRuleMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "DunningRuleCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionDunningRuleType" }, "attributes": { "$ref": "#/components/schemas/DunningRuleAttributes" } } }, "DunningRuleUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionDunningRuleType" }, "attributes": { "$ref": "#/components/schemas/DunningRuleUpdateAttributes" } } }, "DunningRuleAttributes": { "description": "The dunning rule attributes you can use to configure your payment retry strategy.\n", "example": { "payment_retry_type": "fixed", "payment_retry_unit": "day", "payment_retry_interval": 1, "payment_retries_limit": 10, "action": "none" }, "required": [ "payment_retry_type", "payment_retries_limit", "action" ], "properties": { "payment_retry_type": { "type": "string", "enum": [ "fixed", "backoff", "tiered" ], "example": "fixed", "description": "The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n", "x-go-type": "model.PaymentRetryType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "payment_retry_interval": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1024, "example": 1, "description": "The number of `payment_interval_unit`s to wait between each payment retry attempt." }, "payment_retry_unit": { "type": "string", "enum": [ "day", "week" ], "example": "day", "description": "The unit of time used to measure the intervals between payment attempts or retries.", "x-go-type": "model.PaymentRetryUnit", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "payment_retry_multiplier": { "type": "number", "format": "double", "minimum": 1, "maximum": 1024, "example": 1, "description": "The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types." }, "payment_retries_limit": { "type": "integer", "format": "int64", "minimum": 0, "example": 5, "description": "The number of times Subscriptions attempts payment retries before `action` is taken." }, "action": { "type": "string", "enum": [ "none", "pause", "close", "suspend" ], "example": "none", "description": "The action to take after all payment attempts for an invoice have failed.\n\n- None - the subscription remains active and Subscriptions does not attempt to retry the payment. However, the subscription is still available for a subscriber to use.\n- Suspend the subscription. Subscriptions does not attempt to retry the payment. A subscriber can choose to pay the outstanding invoice. However, a subscriber cannot renew their subscription; a merchandizer must renew the subscription on behalf of the subscriber.\n- close a subscription. The subscription ends and it's status becomes `inactive`. However, a merchandizer can choose to resume the subscription if a subscriber pays the outstanding payment.\n", "x-go-type": "model.DunningAction", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "default": { "type": "boolean", "example": false, "description": "Set to `true` if you want this rule to be the default for the store." } } }, "DunningRuleUpdateAttributes": { "properties": { "payment_retry_type": { "type": "string", "enum": [ "fixed", "backoff", "tiered" ], "example": "fixed", "description": "The strategy used to make payments. Always `fixed`. This means payments are retried on a fixed schedule as defined by the `payment_retry_unit` and `payment_retry_interval`, for example, every two days.\n", "x-go-type": "model.PaymentRetryType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "payment_retry_interval": { "type": "integer", "format": "int64", "minimum": 1, "maximum": 1024, "example": 1, "description": "The number of `payment_interval_unit`s to wait between each payment retry attempt.", "nullable": true }, "payment_retry_unit": { "type": "string", "enum": [ "day", "week" ], "example": "day", "description": "The unit of time used to measure the intervals between payment attempts or retries.", "nullable": true, "x-go-type": "model.PaymentRetryUnit", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "payment_retry_multiplier": { "type": "number", "format": "double", "minimum": 1, "maximum": 1024, "example": 1, "description": "The multiplier that increases the interval between consecutive each payment attempts or retries. This is typically used to gradually extend the time between retries. Allowing more time between attempts as failures persist, helps reduce the risk of triggering multiple failures in a short period and gives the subscriber more time to resolve the issue. Must only be set for backup types.", "nullable": true }, "payment_retries_limit": { "type": "integer", "format": "int64", "minimum": 0, "example": 5, "description": "The number of times Subscriptions attempts payment retries before `action` is taken." }, "action": { "type": "string", "enum": [ "none", "pause", "close", "suspend" ], "example": "none", "description": "The action to take after all payment attempts for an invoice have failed.", "x-go-type": "model.DunningAction", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "default": { "type": "boolean", "example": false, "description": "Set to `true` if you want this rule to be the default for the store." } } }, "ProrationPolicy": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/ProrationPolicyType" }, "attributes": { "$ref": "#/components/schemas/ProrationPolicyResponseAttributes" }, "meta": { "$ref": "#/components/schemas/ProrationPolicyMeta" } } }, "ProrationPolicyUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/ProrationPolicyType" }, "attributes": { "$ref": "#/components/schemas/ProrationPolicyUpdateAttributes" } } }, "ProrationPolicyRelationshipAttributes": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ProrationPolicyType" }, "id": { "$ref": "#/components/schemas/UUID" } } }, "ProrationPolicyUpdateRelationshipAttributes": { "type": "object", "nullable": true, "required": [ "type", "id" ], "properties": { "type": { "$ref": "#/components/schemas/ProrationPolicyType" }, "id": { "$ref": "#/components/schemas/UUID" } } }, "ProrationPolicyResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/ProrationPolicyAttributes" } ] }, "ProrationPolicyCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/ProrationPolicyType" }, "attributes": { "$ref": "#/components/schemas/ProrationPolicyAttributes" } } }, "ProrationPolicyAttributes": { "required": [ "name", "rounding" ], "properties": { "name": { "type": "string", "description": "A name for the proration policy.", "example": "Main Policy", "minLength": 3, "maxLength": 1024 }, "rounding": { "type": "string", "description": "When rounding in proration, you must decide how to round the units of time used to calculate the charges.\n\n- round up to the next unit, ensuring subscribers are charged slightly more to cover any partial use.\n- round down to the previous whole unit, providing subscribers with a slight benefit by not charging for partial use.\n- round to the nearest whole unit, whether up or down, based on standard rounding rules. For example, rounding 0.5 up and rounding 0.5 down.\n", "enum": [ "up", "down", "nearest" ], "example": "up", "x-go-type": "model.ProrationPolicyRounding", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "external_ref": { "$ref": "#/components/schemas/ExternalRef" } } }, "ProrationPolicyUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "description": "The name of the proration policy.", "minLength": 3, "maxLength": 1024, "example": "Main Policy" }, "rounding": { "type": "string", "description": "Whether to round up or down", "enum": [ "up", "down", "nearest" ], "example": "up", "x-go-type": "model.ProrationPolicyRounding", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } } } }, "ProrationPolicyMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "OfferingPricingOptionCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionOfferingPricingOptionType" }, "attributes": { "$ref": "#/components/schemas/PricingOptionAttributes" } } }, "PricingOptionResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/PricingOptionAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "PricingOptionAttributes": { "required": [ "name", "billing_interval_type", "billing_frequency", "plan_length", "end_behavior", "can_pause", "can_resume", "can_cancel" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "A name for the pricing option.", "example": "Monthly", "minLength": 3, "maxLength": 1024 }, "description": { "type": "string", "description": "The pricing option description to display to customers.", "maxLength": 1024, "example": "A monthly subscription." }, "billing_interval_type": { "type": "string", "description": "The unit of time that billing intervals are measured.", "example": "month", "enum": [ "day", "week", "month", "year" ], "x-go-type": "model.BillingIntervalType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "billing_frequency": { "type": "integer", "description": "The number of intervals between issuing bills.", "example": 1, "minimum": 1 }, "trial_period": { "type": "integer", "description": "The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.", "example": 7, "minimum": 0 }, "lead_time": { "$ref": "#/components/schemas/LeadTime" }, "notification_schedule": { "type": "array", "x-go-type-skip-optional-pointer": true, "items": { "$ref": "#/components/schemas/NotificationSchedule" } }, "plan_length": { "type": "integer", "description": "The number of intervals that the subscription runs for.", "example": 12, "minimum": 1 }, "end_behavior": { "type": "string", "description": "Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.", "example": "close", "enum": [ "close", "roll" ], "x-go-type": "model.EndBehavior", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "can_pause": { "type": "boolean", "description": "The subscriber can pause a subscription.", "example": false }, "can_resume": { "type": "boolean", "description": "The subscriber can resume a paused subscription.", "example": false }, "can_cancel": { "type": "boolean", "description": "The subscriber can cancel a subscription.", "example": false }, "base_price_percentage": { "type": "number", "format": "double", "description": "A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.", "example": 90, "minimum": 0, "maximum": 100 }, "fixed_price": { "$ref": "#/components/schemas/Price" } } }, "PricingOptionUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "example": "Monthly", "minLength": 3, "maxLength": 1024 }, "description": { "type": "string", "description": "The pricing option description to display to customers.", "example": "A monthly subscription.", "maxLength": 1024, "nullable": true }, "billing_interval_type": { "type": "string", "description": "The unit of time in which billing intervals are measured.", "example": "month", "enum": [ "day", "week", "month", "year" ], "x-go-type": "model.BillingIntervalType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "billing_frequency": { "type": "integer", "description": "The number of intervals between issuing bills.", "example": 1, "minimum": 1 }, "trial_period": { "type": "integer", "description": "The number of intervals from the start of the subscription before billing starts. Used with `billing_interval_type`. For example, if `billing_interval_type` is `months`, and `trial_period` is `1`, the trial period is 1 month.", "example": 7, "minimum": 0, "nullable": true }, "plan_length": { "type": "integer", "description": "The length of time for which a subscription plan is valid. For example, six months after which the plan is renewed.", "example": 12, "minimum": 1 }, "lead_time": { "$ref": "#/components/schemas/NullableLeadTime" }, "notification_schedule": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationSchedule" } }, "end_behavior": { "type": "string", "description": "Enables you to specify recurring payments. If `end_behavior` is `roll`, customers pay regularly and repeatedly. If `end_behavior` is `close`, customers pay a total amount in a limited number of partial payments.", "example": "close", "enum": [ "close", "roll" ], "x-go-type": "model.EndBehavior", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "can_pause": { "type": "boolean", "description": "The subscriber can pause a subscription.", "example": false }, "can_resume": { "type": "boolean", "description": "The subscriber can resume a paused subscription.", "example": false }, "can_cancel": { "type": "boolean", "description": "The subscriber can cancel a subscription.", "example": false }, "base_price_percentage": { "type": "number", "format": "double", "description": "A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.", "example": 90, "minimum": 0, "maximum": 100, "nullable": true }, "fixed_price": { "$ref": "#/components/schemas/NullablePrice" } } }, "BuildOffering": { "required": [ "name", "plans", "pricing_options" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "The name of the offering.", "minLength": 3, "maxLength": 1024, "example": "Magazine" }, "description": { "type": "string", "description": "The offering description to display to customers.", "maxLength": 1024, "example": "A lovely magazine that is published every month." }, "proration_policy_id": { "type": "string", "description": "The unique ID or external ref of the proration policy", "example": "11111111-2222-3333-4444-555555555555" }, "configured_features": { "$ref": "#/components/schemas/OfferingBuildConfiguredFeatures" }, "pricing_option_associations": { "$ref": "#/components/schemas/OfferingBuildPricingOptionAssociations" }, "features": { "type": "array", "description": "Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering", "minItems": 1, "items": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRef" }, { "$ref": "#/components/schemas/FeatureAttributes" }, { "$ref": "#/components/schemas/UUID" } ] } }, "plans": { "type": "array", "description": "Plan information to be created within the offering", "minItems": 1, "items": { "anyOf": [ { "$ref": "#/components/schemas/OfferingPlanAttributes" } ] } }, "pricing_options": { "type": "array", "description": "Pricing options information to be created within the offering", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingOptionAttributes" } } } }, "Offering": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingType" }, "attributes": { "$ref": "#/components/schemas/OfferingResponseAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/OfferingMeta" } } }, "OfferingIncludes": { "readOnly": true, "properties": { "features": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingFeature" } }, "plans": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingPlan" } }, "pricing_options": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingPricingOption" } } } }, "OfferingMeta": { "readOnly": true, "required": [ "owner", "timestamps", "external_plan_refs" ], "properties": { "external_plan_refs": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingPlanExternalRefMeta" } }, "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "OfferingCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionOfferingType" }, "attributes": { "$ref": "#/components/schemas/OfferingAttributes" }, "relationships": { "$ref": "#/components/schemas/OfferingRelationships" } } }, "OfferingPlanUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingPlanType" }, "attributes": { "$ref": "#/components/schemas/OfferingPlanUpdateAttributes" } } }, "FeatureConfigAccessAttributes": { "description": "Configures an access feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "access" ], "example": "access" } } }, "FeatureConfigPromotionAttributes": { "description": "Configures a promotion feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The tag of the specific promotion that it to be made available must be supplied.", "required": [ "type", "tag" ], "properties": { "type": { "type": "string", "enum": [ "promotion" ], "example": "promotion" }, "tag": { "$ref": "#/components/schemas/FeatureTag" } } }, "FeatureConfigUsageAttributes": { "description": "Configures a usage feature against a plan in an offering, indicating that the referenced feature is a benefit of that plan. The default value that the usage metrics adopts must be supplied.", "required": [ "type", "default_value" ], "properties": { "type": { "type": "string", "enum": [ "usage" ], "example": "usage" }, "default_value": { "type": "integer", "description": "The default initial value", "example": 10 } } }, "FeaturePlanConfiguration": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/FeatureConfigAccessAttributes" }, { "$ref": "#/components/schemas/FeatureConfigPromotionAttributes" }, { "$ref": "#/components/schemas/FeatureConfigUsageAttributes" } ], "discriminator": { "propertyName": "type", "mapping": { "access": "#/components/schemas/FeatureConfigAccessAttributes", "promotion": "#/components/schemas/FeatureConfigPromotionAttributes", "usage": "#/components/schemas/FeatureConfigUsageAttributes" } }, "required": [ "type" ], "properties": { "type": { "description": "The type of feature, one of access, promotion or usage.", "enum": [ "access", "promotion", "usage" ], "example": "access", "x-go-type": "string" } } }, "FeaturePlanConfigurationUpdate": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/FeatureConfigAccessAttributes" }, { "$ref": "#/components/schemas/FeatureConfigPromotionAttributes" }, { "$ref": "#/components/schemas/FeatureConfigUsageAttributes" } ], "discriminator": { "propertyName": "type", "mapping": { "access": "#/components/schemas/FeatureConfigAccessAttributes", "promotion": "#/components/schemas/FeatureConfigPromotionAttributes", "usage": "#/components/schemas/FeatureConfigUsageAttributes" } }, "required": [ "type" ], "properties": { "type": { "description": "The type of feature, one of access, promotion or usage.", "enum": [ "access", "promotion", "usage" ], "example": "access", "x-go-type": "string" } } }, "OfferingBuildPlanPricingOptions": { "type": "array", "items": { "type": "string", "description": "The unique ID or external ref of the pricing option", "example": "11111111-2222-3333-4444-555555555555" } }, "OfferingBuildPricingOptionAssociations": { "type": "object", "description": "A map of plans keyed by plan UUID or external_ref to a list of associated pricing options, similarly keyed.", "additionalProperties": { "$ref": "#/components/schemas/OfferingBuildPlanPricingOptions" } }, "OfferingBuildConfiguredFeatures": { "type": "object", "description": "Map of feature configurations keyed by plan UUID or external_ref", "additionalProperties": { "$ref": "#/components/schemas/OfferingBuildPlanFeatures" } }, "OfferingBuildPlanFeatures": { "type": "object", "description": "A map of configurations indicating which features are available for the plan", "additionalProperties": { "$ref": "#/components/schemas/FeaturePlanConfiguration" } }, "OfferingFeatureUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureUpdateAttributes" } } }, "OfferingFeature": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingFeatureType" }, "attributes": { "$ref": "#/components/schemas/FeatureResponseAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/FeatureMeta" } } }, "OfferingPlan": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingPlanType" }, "attributes": { "$ref": "#/components/schemas/OfferingPlanResponseAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/PlanMeta" } } }, "OfferingPricingOptionUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingPricingOptionType" }, "attributes": { "$ref": "#/components/schemas/PricingOptionUpdateAttributes" } } }, "OfferingPricingOption": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingPricingOptionType" }, "attributes": { "$ref": "#/components/schemas/PricingOptionResponseAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/OfferingPricingOptionMeta" } } }, "OfferingPricingOptionMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "prices": { "$ref": "#/components/schemas/OfferingPricingOptionPrices" }, "price": { "$ref": "#/components/schemas/Price" }, "display_price": { "$ref": "#/components/schemas/DisplayPrice" }, "active_pricing_option": { "$ref": "#/components/schemas/ActivePricingOption" }, "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "OfferingPricingOptionPrices": { "type": "object", "description": "The price of each plan within the offering that this pricing option may be applied to.", "readOnly": true, "additionalProperties": { "$ref": "#/components/schemas/OfferingPricingOptionPriceForPlan" } }, "OfferingPricingOptionPriceForPlan": { "readOnly": true, "properties": { "price": { "$ref": "#/components/schemas/Price" }, "display_price": { "$ref": "#/components/schemas/DisplayPrice" } } }, "OfferingFeatureAttach": { "description": "A list of feature IDs to attach to the offering. See [**List Features**](/docs/api/subscriptions/list-features).", "required": [ "features" ], "properties": { "features": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/UUID" } } } }, "OfferingUpdate": { "anyOf": [ { "required": [ "attributes" ] }, { "required": [ "relationships" ] } ], "required": [ "id", "type" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionOfferingType" }, "attributes": { "$ref": "#/components/schemas/OfferingUpdateAttributes" }, "relationships": { "$ref": "#/components/schemas/OfferingUpdateRelationships" } } }, "OfferingResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/OfferingAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "OfferingAttributes": { "required": [ "name" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "The name of the offering.", "minLength": 3, "maxLength": 1024, "example": "Magazine" }, "description": { "type": "string", "description": "The offering description to display to customers.", "maxLength": 1024, "example": "A lovely magazine that is published every month." } } }, "OfferingUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "description": "The name of the offering.", "minLength": 3, "maxLength": 1024, "example": "Magazine" }, "description": { "type": "string", "description": "The offering description to display to customers.", "maxLength": 1024, "example": "A lovely magazine that is published every month.", "nullable": true } } }, "OfferingRelationships": { "properties": { "proration_policy": { "$ref": "#/components/schemas/ProrationPolicyRelationshipAttributes" } } }, "OfferingUpdateRelationships": { "properties": { "proration_policy": { "$ref": "#/components/schemas/ProrationPolicyUpdateRelationshipAttributes" } } }, "BuildSubscriptionOrder": { "description": "A subscription may optionally be associated with an item in an order by supplying both the order ID and the ID of the item within that order.", "required": [ "order_id", "order_item_id" ], "properties": { "order_id": { "$ref": "#/components/schemas/UUID" }, "order_item_id": { "$ref": "#/components/schemas/UUID" } } }, "BuildSubscription": { "required": [ "account_id", "currency", "name", "email", "manual_payments" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "account_id": { "$ref": "#/components/schemas/UUID" }, "address_id": { "$ref": "#/components/schemas/UUID" }, "offering_external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "offering_id": { "$ref": "#/components/schemas/UUID" }, "plan_id": { "$ref": "#/components/schemas/UUID" }, "pricing_option_id": { "$ref": "#/components/schemas/UUID" }, "currency": { "$ref": "#/components/schemas/CurrencyIdentifier" }, "payment_authority": { "$ref": "#/components/schemas/CreatePaymentAuthority" }, "manual_payments": { "$ref": "#/components/schemas/ManualPayments" }, "name": { "type": "string", "minLength": 3, "maxLength": 1024, "example": "Albert Einstein" }, "email": { "type": "string", "format": "email", "minLength": 3, "maxLength": 1024, "example": "albert@elasticpath.com" }, "pending": { "type": "boolean", "description": "Whether a subscription is pending activation or not. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription).", "example": false }, "first_invoice_paid": { "type": "boolean", "description": "Indicates that payment for the first billing period of the subscription has already been taken. As well as creating the subscription a settled invoice is created to cover the first period.", "example": false }, "started_at": { "description": "When importing an active subscription from an existing system you can specify the date and time of the start of the most recent period. This may only be supplied when `first_invoice_paid` is true. As well as creating the subscription a settled invoice is created to cover the correct billing period.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "override_first_period_end_date": { "description": "Optional. May only be set when `started_at` is set. When supplied, overrides the default first billing period end (start + 1 interval). The first billing period runs from the subscription start date to this date. The subscriber is charged the standard period price for the first period. Subsequent billing periods start from this date. Must be after the subscription start date.", "type": "string", "format": "date-time", "example": "2027-02-01T00:00:00Z" }, "offering": { "$ref": "#/components/schemas/OfferingAttributes" }, "features": { "type": "array", "description": "Either references of existing features (id or external_ref) to be attached to the offering or feature information to be created directly within the offering", "minItems": 1, "items": { "anyOf": [ { "$ref": "#/components/schemas/ExternalRef" }, { "$ref": "#/components/schemas/FeatureAttributes" }, { "$ref": "#/components/schemas/UUID" } ] } }, "plans": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PlanAttributesAndSelectedMeta" } }, "pricing_options": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/PricingOptionAttributesAndSelectedMeta" } }, "configured_features": { "$ref": "#/components/schemas/OfferingBuildConfiguredFeatures" }, "pricing_option_associations": { "$ref": "#/components/schemas/OfferingBuildPricingOptionAssociations" }, "selected_plan": { "$ref": "#/components/schemas/ExternalRef" }, "selected_pricing_option": { "$ref": "#/components/schemas/ExternalRef" }, "order": { "$ref": "#/components/schemas/BuildSubscriptionOrder" }, "meta": { "$ref": "#/components/schemas/SubscriptionMeta" } } }, "PricingOptionAttributesAndSelectedMeta": { "allOf": [ { "$ref": "#/components/schemas/PricingOptionAttributes" }, { "$ref": "#/components/schemas/SelectedMeta" } ] }, "PlanAttributesAndSelectedMeta": { "allOf": [ { "$ref": "#/components/schemas/PlanAttributes" }, { "$ref": "#/components/schemas/SelectedMeta" } ] }, "SelectedMeta": { "properties": { "meta": { "$ref": "#/components/schemas/SelectedMetaAttributes" } } }, "SelectedMetaAttributes": { "properties": { "selected": { "type": "boolean", "example": true, "description": "One item must be selected for use in the subscription" } } }, "Subscription": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/SubscriptionMeta" } } }, "ManageSubscriptionPlans": { "type": "object", "required": [ "type", "plans" ], "properties": { "type": { "type": "string", "enum": [ "detach" ], "example": "detach", "x-go-type": "model.ManagePlansAction", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "plans": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/UUID" } } } }, "SubscriptionUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionUpdateAttributes" } } }, "SubscriptionUpdateAttributes": { "properties": { "pricing_option_id": { "type": "string", "format": "uuid", "x-go-type": "uuid.UUID", "x-go-type-import": { "name": "uuid", "path": "github.com/google/uuid" }, "example": "00000000-0000-0000-0000-000000000001" }, "plan_id": { "type": "string", "format": "uuid", "x-go-type": "uuid.UUID", "x-go-type-import": { "name": "uuid", "path": "github.com/google/uuid" }, "example": "00000000-0000-0000-0000-000000000001" }, "address_id": { "type": "string", "format": "UUID", "nullable": true, "x-go-type": "uuid.UUID", "x-go-type-import": { "name": "uuid", "path": "github.com/google/uuid" }, "example": "00000000-0000-0000-0000-000000000001" }, "payment_authority": { "$ref": "#/components/schemas/PaymentAuthority" }, "go_live_after": { "description": "The date and time a `pending` subscription goes live and becomes active. See [Creating a pending subscription](/docs/api/subscriptions/subscriptions#creating-a-pending-subscription).", "type": "string", "example": "2017-01-10T11:41:19.244842Z", "nullable": true } } }, "SubscriptionIncludes": { "readOnly": true, "properties": { "plans": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingPlan" } }, "pricing_options": { "type": "array", "items": { "$ref": "#/components/schemas/OfferingPricingOption" } } } }, "SubscriptionMeta": { "readOnly": true, "required": [ "owner", "timestamps", "status", "canceled", "paused", "closed", "pending", "suspended", "invoice_after", "manual_payments", "first_invoice_prepaid" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/SubscriptionTimestamps" }, "status": { "$ref": "#/components/schemas/Status" }, "state": { "$ref": "#/components/schemas/SubscriptionState" }, "manual_payments": { "$ref": "#/components/schemas/ManualPayments" }, "first_invoice_prepaid": { "type": "boolean", "description": "Indicates that the first billing period of this subscription was paid for outside of the subscriptions service.", "example": false }, "canceled": { "type": "boolean", "description": "Whether a subscription is canceled or not.", "example": true }, "paused": { "type": "boolean", "description": "Whether a subscription is paused or not.", "example": true }, "closed": { "type": "boolean", "description": "Whether a subscription is closed or not.", "example": true }, "suspended": { "type": "boolean", "description": "Whether a subscription is suspended or not.", "example": false }, "pending": { "type": "boolean", "description": "Whether a subscription is pending activation or not.", "example": false }, "invoice_after": { "description": "The time when the subscription becomes eligible for a new invoice. The next invoice will be generated at the next billing run after this point.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "pending_price_change": { "$ref": "#/components/schemas/SubscriptionPriceChanges" }, "price_update_history": { "description": "A history of price updates that have been applied to this subscription.", "type": "array", "x-go-type-skip-optional-pointer": true, "items": { "$ref": "#/components/schemas/SubscriptionPriceUpdateHistoryEntry" } } } }, "SubscriptionTimestamps": { "allOf": [ { "$ref": "#/components/schemas/Timestamps" }, { "properties": { "canceled_at": { "description": "The date and time a subscription was cancelled.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "paused_at": { "description": "The date and time a subscription was paused.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "resumed_at": { "description": "The date and time a subscription was resumed.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "end_date": { "description": "The date and time a subscription will end.\n- If the subscription offering pricing option end behavior is `close`, `end_date` is set to the billing period end date upon subscription creation.\n- If the subscription offering pricing option end behavior is \"roll\": `end_date` is set to the billing period end date when the subscription is cancelled.\n", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "go_live_after": { "description": "The date and time a subscription will go live and become active.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "go_live": { "description": "The date and time a subscription was released from the pending state and made active.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } } ] }, "SubscriptionAttributes": { "required": [ "account_id", "pricing_option_id", "plan_id", "offering", "currency", "name", "email" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "account_id": { "$ref": "#/components/schemas/UUID" }, "address_id": { "$ref": "#/components/schemas/UUID" }, "offering": { "$ref": "#/components/schemas/Offering" }, "pricing_option_id": { "$ref": "#/components/schemas/UUID" }, "plan_id": { "$ref": "#/components/schemas/UUID" }, "currency": { "$ref": "#/components/schemas/CurrencyIdentifier" }, "payment_authority": { "$ref": "#/components/schemas/PaymentAuthority" } } }, "ChangeState": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionStateType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionStateAttributes" } } }, "SubscriptionStateAttributes": { "required": [ "action" ], "properties": { "action": { "$ref": "#/components/schemas/SubscriptionStateAction" }, "cancel_immediately": { "type": "boolean", "default": false, "example": false, "description": "When `action` is `cancel`, if `true`, the subscription moves to `inactive` immediately with entitlements updated in this request,\nand a `canceled` event is emitted (not `pending_cancel`). Omitted or `false` preserves end-of-period cancellation.\nSubscribers may not set this to `true` and will receive a 403.\n\nImmediate cancellation does **not** trigger any sort of refund; those require separate API flows.\n" } } }, "SubscriptionStateType": { "type": "string", "description": "This represents the type of resource object being returned. Always `subscription_state`.", "example": "subscription_state", "enum": [ "subscription_state" ] }, "SubscriptionStateAction": { "type": "string", "description": "The subscription lifecycle is the states that a subscription can go through when a customer subscribes to a service or a plan.\n\nA subscription can have the following states; `canceled`, `paused`, or `resumed`.\n\nSee [**Managing the subscription lifecycle**](/docs/api/subscriptions/subscriptions#manag", "example": "cancel", "enum": [ "cancel", "pause", "resume", "pending" ], "x-go-type": "model.SubscriptionAction", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "StateMeta": { "readOnly": true, "required": [ "created_at" ], "properties": { "created_at": { "description": "The date and time a resource was created.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "SubscriptionState": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionStateType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionStateAttributes" }, "meta": { "$ref": "#/components/schemas/StateMeta" } } }, "ManualPayments": { "type": "boolean", "example": false, "default": false, "description": "When configured to true, no payment gateway is used and a pending payment is created. See [External Payments](/docs/api/subscriptions/invoices#external-payments)." }, "PaymentAuthority": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/PaymentAuthorityEPPayments" }, { "$ref": "#/components/schemas/PaymentAuthorityStripe" }, { "$ref": "#/components/schemas/PaymentAuthorityAuthorizeNet" } ], "discriminator": { "propertyName": "type", "mapping": { "elastic_path_payments_stripe": "#/components/schemas/PaymentAuthorityEPPayments", "stripe_payment_intents": "#/components/schemas/PaymentAuthorityStripe", "authorize_net": "#/components/schemas/PaymentAuthorityAuthorizeNet" } }, "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "elastic_path_payments_stripe", "enum": [ "authorize_net", "elastic_path_payments_stripe", "stripe_payment_intents" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } } } }, "NullablePaymentAuthority": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/PaymentAuthorityEPPayments" }, { "$ref": "#/components/schemas/PaymentAuthorityStripe" }, { "$ref": "#/components/schemas/PaymentAuthorityAuthorizeNet" } ], "discriminator": { "propertyName": "type", "mapping": { "elastic_path_payments_stripe": "#/components/schemas/PaymentAuthorityEPPayments", "stripe_payment_intents": "#/components/schemas/PaymentAuthorityStripe", "authorize_net": "#/components/schemas/PaymentAuthorityAuthorizeNet" } }, "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "elastic_path_payments_stripe", "enum": [ "authorize_net", "elastic_path_payments_stripe", "stripe_payment_intents" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } } } }, "CreatePaymentAuthority": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CreatePaymentAuthorityEPPayments" }, { "$ref": "#/components/schemas/CreatePaymentAuthorityStripe" }, { "$ref": "#/components/schemas/CreatePaymentAuthorityAuthorizeNet" } ], "discriminator": { "propertyName": "type", "mapping": { "elastic_path_payments_stripe": "#/components/schemas/CreatePaymentAuthorityEPPayments", "stripe_payment_intents": "#/components/schemas/CreatePaymentAuthorityStripe", "authorize_net": "#/components/schemas/CreatePaymentAuthorityAuthorizeNet" } }, "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "elastic_path_payments_stripe", "enum": [ "authorize_net", "elastic_path_payments_stripe", "stripe_payment_intents" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } } } }, "CreatePaymentAuthorityAuthorizeNet": { "type": "object", "required": [ "type", "payment_profile_id", "customer_profile_id" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "authorize_net", "enum": [ "authorize_net" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "payment_profile_id": { "description": "The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "1511660856" }, "customer_profile_id": { "description": "The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "1511736979" } } }, "CreatePaymentAuthorityEPPayments": { "writeOnly": true, "type": "object", "required": [ "type", "customer_id", "card_id" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "elastic_path_payments_stripe", "enum": [ "elastic_path_payments_stripe" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "customer_id": { "description": "The unique identifier for a customer.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "cus_OPfKlxWV3hp9h6" }, "card_id": { "description": "The unique identifier of the card used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "card_8Diw3FQPhxK27WADPVMeXieP" } } }, "CreatePaymentAuthorityStripe": { "writeOnly": true, "type": "object", "required": [ "type", "customer_id", "card_id" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "stripe_payment_intents", "enum": [ "stripe_payment_intents" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "customer_id": { "description": "The unique identifier for a customer.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "cus_OPfKlxWV3hp9h6" }, "card_id": { "description": "The unique identifier of the card used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "card_8Diw3FQPhxK27WADPVMeXieP" } } }, "PaymentAuthorityAuthorizeNet": { "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "authorize_net", "enum": [ "authorize_net" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "payment_profile_id": { "description": "The customer's payment profile id, unique to Authorize.net, used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "1511660856" }, "customer_profile_id": { "description": "The customer's profile id, unique to Authorize.net, used to facilitate payment of the subscription.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "1511736979" } } }, "PaymentAuthorityEPPayments": { "writeOnly": true, "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "elastic_path_payments_stripe", "enum": [ "elastic_path_payments_stripe" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "customer_id": { "description": "The unique identifier for a customer.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "cus_OPfKlxWV3hp9h6" }, "card_id": { "description": "The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).", "type": "string", "minLength": 3, "maxLength": 1024, "example": "card_8Diw3FQPhxK27WADPVMeXieP" } } }, "PaymentAuthorityStripe": { "writeOnly": true, "type": "object", "required": [ "type" ], "properties": { "type": { "description": "The name of the payment gateway facilitating the secure transmission of payment data.", "type": "string", "example": "stripe_payment_intents", "enum": [ "stripe_payment_intents" ], "x-go-type": "paymentgateways.GatewayName", "x-go-type-import": { "name": "paymentgateways", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/paymentgateways" } }, "customer_id": { "description": "The unique identifier for a customer.", "type": "string", "minLength": 3, "maxLength": 1024, "example": "cus_OPfKlxWV3hp9h6" }, "card_id": { "description": "The unique identifier of the card used to facilitate payment of the subscription. If a card payment fails, you can use the `card_id` and `customer_id` attributes to program your front-end implementation to allow your preferred payment service provider to update a subscription with new card details. See [Card declines](/docs/api/subscriptions/invoices#card-declines).", "type": "string", "minLength": 3, "maxLength": 1024, "example": "card_8Diw3FQPhxK27WADPVMeXieP" } } }, "Import": { "required": [ "type", "meta", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionImportType" }, "attributes": { "$ref": "#/components/schemas/ImportAttributes" }, "meta": { "$ref": "#/components/schemas/ImportMeta" } } }, "ImportAttributes": { "required": [ "status" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "status": { "type": "string", "description": "The status of job.\n- **pending** - Commerce has received the request but is currently busy processing other requests.\n- **started** - Commerce has started processing the job.\n- **success** - The job has successfully completed.\n- **failed** - The job has failed.\n", "enum": [ "pending", "started", "success", "failed" ], "example": "pending", "x-go-type": "model.JobStatus", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } } } }, "ImportMeta": { "readOnly": true, "required": [ "owner", "timestamps", "records" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/JobTimestamps" }, "records": { "$ref": "#/components/schemas/ImportRecords" } } }, "ImportRecords": { "type": "object", "description": "You can track the number of records imported to ensure the completeness, accuracy and integrity of the import. Uploaded shows the number of records ready to be imported into Subscriptions. However, this does not mean they are valid subscription objects, only that they have the correct type and their", "required": [ "uploaded", "imported" ], "properties": { "uploaded": { "type": "object", "properties": { "subscription_feature": { "description": "The total number of features uploaded.", "type": "integer", "example": 50000 }, "subscription_subscriber": { "description": "The total number of subscribers uploaded.", "type": "integer", "example": 50000 }, "subscription_offering": { "description": "The total number of offerings uploaded.", "type": "integer", "example": 50000 }, "subscription": { "description": "The total number of subscriptions uploaded.", "type": "integer", "example": 50000 } }, "required": [ "subscription_feature", "subscription_subscriber", "subscription_offering", "subscription" ] }, "imported": { "properties": { "subscription_feature": { "description": "The total number of features uploaded.", "type": "integer", "example": 50000 }, "subscription_subscriber": { "description": "The total number of subscribers imported.", "type": "integer", "example": 45090 }, "subscription_offering": { "description": "The total number of offerings imported.", "type": "integer", "example": 45090 }, "subscription": { "description": "The total number of subscriptions imported.", "type": "integer", "example": 45090 } }, "required": [ "subscription_feature", "subscription_subscriber", "subscription_offering", "subscription" ] } } }, "Job": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionJobType" }, "attributes": { "$ref": "#/components/schemas/JobResponseAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/JobMeta" } } }, "JobMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/JobTimestamps" }, "report": { "$ref": "#/components/schemas/JobReport" } } }, "JobReport": { "description": "You can track your Subscriptions billing, tax, and payment operations using reports.", "oneOf": [ { "$ref": "#/components/schemas/BillingRunReport" }, { "$ref": "#/components/schemas/TaxRunReport" }, { "$ref": "#/components/schemas/PaymentRunReport" }, { "$ref": "#/components/schemas/NotificationRunReport" }, { "$ref": "#/components/schemas/SubscriptionUpdateReport" } ] }, "BillingRunReport": { "required": [ "invoices_ready_for_payment", "invoices_tax_required", "invoice_failures", "total_ready_for_payment", "total_tax_required" ], "properties": { "invoices_ready_for_payment": { "description": "The total number of invoices created that are ready for payment.", "type": "integer", "example": 100 }, "invoices_tax_required": { "description": "The total number of invoices created that need taxes to be applied before payment can be made.", "type": "integer", "example": 100 }, "invoice_failures": { "description": "The total number of invoices that were scheduled but creation failed.", "type": "integer", "example": 0 }, "total_ready_for_payment": { "allOf": [ { "description": "The total amount ready for payment invoiced in the billing run, segmented by currency." }, { "$ref": "#/components/schemas/Price" } ] }, "total_tax_required": { "allOf": [ { "description": "The total amount (excluding tax) invoiced in the billing run but still requiring taxes, segmented by currency." }, { "$ref": "#/components/schemas/Price" } ] } } }, "TaxRunReport": { "required": [ "invoices_updated", "invoice_failures" ], "properties": { "invoices_updated": { "description": "The total number of invoices to which tax was successfully added.", "type": "integer", "example": 100 }, "invoice_failures": { "description": "The total number of invoices to which tax could not be added.", "type": "integer", "example": 0 } } }, "PaymentRunReport": { "required": [ "total_payment_attempts", "failed_payments", "total_collected" ], "properties": { "total_payment_attempts": { "description": "The total number of invoices for which payment was attempted.", "type": "integer", "example": 100 }, "failed_payments": { "description": "The number of failed payment attempts.", "type": "integer", "example": 0 }, "total_collected": { "allOf": [ { "description": "The total amount collected by the payment run, segmented by currency." }, { "$ref": "#/components/schemas/Price" } ] } } }, "NotificationRunReport": { "required": [ "total_notifications_sent", "failed_notifications" ], "properties": { "total_notifications_sent": { "description": "The total number of notifications sent.", "type": "integer", "example": 100 }, "failed_notifications": { "description": "The number of failed notifications.", "type": "integer", "example": 0 } } }, "SubscriptionUpdateReport": { "required": [ "subscriptions_updated", "subscription_failures", "total_processed" ], "properties": { "subscriptions_updated": { "description": "The total number of subscriptions updated.", "type": "integer", "example": 100 }, "subscription_failures": { "description": "The total number of subscriptions that failed to be updated.", "type": "integer", "example": 0 }, "total_processed": { "description": "The total number of subscriptions processed.", "type": "integer", "example": 100 } } }, "JobTimestamps": { "allOf": [ { "$ref": "#/components/schemas/Timestamps" }, { "properties": { "started_at": { "description": "The date and time a job is started.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "finished_at": { "description": "The date and time a job finished.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } } ] }, "JobCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionJobType" }, "attributes": { "$ref": "#/components/schemas/JobCreateAttributes" } } }, "JobResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/JobCreateAttributes" }, { "$ref": "#/components/schemas/JobAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "ScheduleJobType": { "type": "string", "description": "The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `payment-run` - a payment run job.\n - `notification-run` - a notification run job.\n", "enum": [ "billing-run", "payment-run", "notification-run" ], "example": "billing-run", "x-go-type": "model.JobType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "JobCreateAttributes": { "required": [ "job_type" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "job_type": { "type": "string", "description": "The type of job. One of the following:\n - `billing-run` - a billing run job.\n - `tax-run` - a tax run job.\n - `payment-run` - a payment run job.\n - `import` - an import job.\n - `notification-run` - a notification run job.\n - `subscription-update` - a subscription update run job.\n", "enum": [ "billing-run", "tax-run", "payment-run", "import", "notification-run", "subscription-update" ], "example": "billing-run", "x-go-type": "string" } }, "oneOf": [ { "$ref": "#/components/schemas/BillingRunJobAttributes" }, { "$ref": "#/components/schemas/TaxRunJobAttributes" }, { "$ref": "#/components/schemas/PaymentRunJobAttributes" }, { "$ref": "#/components/schemas/ImportJobAttributes" }, { "$ref": "#/components/schemas/NotificationRunJobAttributes" }, { "$ref": "#/components/schemas/SubscriptionUpdateRunJobAttributes" } ], "discriminator": { "propertyName": "job_type", "mapping": { "billing-run": "#/components/schemas/BillingRunJobAttributes", "tax-run": "#/components/schemas/TaxRunJobAttributes", "payment-run": "#/components/schemas/PaymentRunJobAttributes", "import": "#/components/schemas/ImportJobAttributes", "notification-run": "#/components/schemas/NotificationRunJobAttributes", "subscription-update": "#/components/schemas/SubscriptionUpdateRunJobAttributes" } } }, "BillingRunJobAttributes": { "required": [ "job_type" ], "properties": { "job_type": { "type": "string", "example": "billing-run" } } }, "TaxRunJobAttributes": { "required": [ "job_type" ], "properties": { "job_type": { "type": "string", "example": "tax-run" }, "taxes": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/InvoiceTaxItems" } } } }, "PaymentRunJobAttributes": { "required": [ "job_type" ], "properties": { "job_type": { "type": "string", "example": "payment-run" } } }, "ImportJobAttributes": { "required": [ "job_type" ], "properties": { "job_type": { "type": "string", "example": "import" } } }, "NotificationRunJobAttributes": { "required": [ "job_type" ], "properties": { "job_type": { "type": "string", "example": "notification-run" } } }, "SubscriptionUpdateRunJobAttributes": { "required": [ "job_type", "price_changes" ], "properties": { "job_type": { "type": "string", "example": "subscription-update" }, "offering_id": { "description": "The ID of the offering whose subscriptions should be updated. Mutually exclusive with `subscription_ids`.\n", "type": "string", "format": "uuid", "x-go-type": "uuid.UUID", "x-go-type-import": { "name": "uuid", "path": "github.com/google/uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, "excluded_subscription_ids": { "description": "Subscriptions to exclude from the price update. Only valid when `offering_id` is provided.\n", "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "x-go-type-skip-optional-pointer": true }, "subscription_ids": { "description": "Specific subscriptions to update. Mutually exclusive with `offering_id`.\n", "type": "array", "items": { "$ref": "#/components/schemas/UUID" }, "x-go-type-skip-optional-pointer": true }, "price_changes": { "$ref": "#/components/schemas/SubscriptionPriceChanges" } } }, "SubscriptionPriceChanges": { "properties": { "plan_prices": { "x-go-type-skip-optional-pointer": true, "additionalProperties": { "$ref": "#/components/schemas/Price" }, "example": { "197a11f4-d341-4594-9574-7fbfbe6a671d": { "USD": { "amount": 100, "includes_tax": false }, "GBP": { "amount": 90, "includes_tax": true } } } }, "pricing_option_prices": { "x-go-type-skip-optional-pointer": true, "additionalProperties": { "$ref": "#/components/schemas/PricingOptionPrice" }, "example": { "83f6b8e3-031c-4f2a-a1d7-b1c83cb5ac3c": { "base_price_percentage": 90 }, "197a11f4-d341-4594-9574-7fbfbe6a671d": { "USD": { "amount": 100, "includes_tax": false }, "GBP": { "amount": 90, "includes_tax": true } } } } } }, "SubscriptionPriceUpdateHistoryEntry": { "description": "A record of the previous prices of a subscription before a price change was applied", "required": [ "price_changes", "valid_until" ], "properties": { "price_changes": { "$ref": "#/components/schemas/SubscriptionPriceChanges" }, "valid_until": { "description": "The date and time when the prices were changed (when these previous prices stopped being active)", "type": "string", "format": "date-time", "example": "2017-01-10T11:41:19.244842Z" } } }, "PricingOptionPrice": { "properties": { "base_price_percentage": { "type": "number", "format": "double", "description": "A percentage discount on the total cost of any plans within an offering. For example, you can configure a percentage that equates the cost of a pricing option to the total value of all plans within the offering, reduced by a percentage. For example, if you specify `10`, a 10% discount is applied to the total value of all repeat plans in an offering.", "example": 90, "minimum": 0, "maximum": 100 }, "fixed_price": { "$ref": "#/components/schemas/Price" } } }, "JobAttributes": { "required": [ "status" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "status": { "type": "string", "description": "The status of job.", "enum": [ "pending", "started", "success", "failed" ], "example": "pending", "x-go-type": "model.JobStatus", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } } } }, "InvoiceTaxItems": { "required": [ "invoice_id", "tax_items" ], "properties": { "invoice_id": { "$ref": "#/components/schemas/UUID" }, "tax_items": { "type": "array", "items": { "$ref": "#/components/schemas/TaxItem" } } } }, "TaxItem": { "required": [ "type", "rate" ], "properties": { "type": { "description": "This represents the type of resource object being returned. Always `tax_item`.", "type": "string", "enum": [ "tax_item" ], "example": "tax_item" }, "name": { "description": "The name that appears on your customer's invoice and usually describes the specific type of tax, for example, `Sales`, `VAT` or `GST`.", "type": "string", "maxLength": 1024, "example": "GST" }, "code": { "description": "The unique identifier assigned to goods and services for taxation purposes.", "type": "string", "maxLength": 1024, "example": "20.0 % S" }, "rate": { "description": "The tax rate is the percentage of the subscription amount that is required to be paid as tax.", "type": "number", "format": "double", "example": 0.2 }, "jurisdiction": { "description": "The geographic area or political entity that has authority to levy and collect taxes.", "type": "string", "maxLength": 1024, "example": "USA" } } }, "InvoiceNotification": { "description": "A notification scheduled for an invoice.", "required": [ "name", "due" ], "properties": { "name": { "description": "The name of the notification schedule that generated this notification.", "type": "string", "example": "7 days before renewal" }, "due": { "description": "The date and time when the notification is due to be sent.", "type": "string", "format": "date-time", "example": "2024-01-24T00:00:00Z" }, "sent_at": { "description": "The date and time when the notification was sent.", "type": "string", "format": "date-time", "example": "2024-01-24T00:00:00Z" } } }, "SubscriptionInvoice": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionInvoiceType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionInvoiceAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" }, "meta": { "$ref": "#/components/schemas/SubscriptionInvoiceMeta" } } }, "UpdateInvoicePayment": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentType" }, "attributes": { "$ref": "#/components/schemas/UpdateInvoicePaymentAttributes" } } }, "UpdateInvoicePaymentAttributes": { "required": [ "success" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the payment was successful." }, "external_payment_id": { "type": "string", "maxLength": 1024, "example": "33e7ec6b-8b34-4c92-a95b-2e2647922e47", "description": "An optional external ID that is specific to the gateway used." }, "failure_detail": { "description": "A message generated by an external payment method that describes why a payment fails.", "type": "string", "example": "Card Failure" }, "payment_taken_at": { "description": "The date and time the invoice payment was taken at.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "SubscriptionInvoicePayment": { "required": [ "id", "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentAttributes" }, "meta": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentMeta" } } }, "SubscriptionInvoiceMeta": { "readOnly": true, "required": [ "owner", "timestamps", "proration_events", "pro_rata_remaining_value", "display_price" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "subscription_id": { "$ref": "#/components/schemas/UUID" }, "subscriber_id": { "$ref": "#/components/schemas/UUID" }, "price": { "$ref": "#/components/schemas/SingleCurrencyPrice" }, "display_price": { "description": "Invoice totals formatted for display (`with_tax`, `without_tax`, `tax`). Amounts are in the\ncurrency's smallest subdivision.\n", "$ref": "#/components/schemas/DisplayPrice" }, "notifications": { "description": "A list of notifications scheduled for this invoice. These are derived from the notification\nschedules configured on the pricing option at the time the invoice was created. Each notification\nhas a due date calculated relative to the billing period end date.\n", "type": "array", "items": { "$ref": "#/components/schemas/InvoiceNotification" } }, "timestamps": { "$ref": "#/components/schemas/InvoiceTimestamps" }, "proration_events": { "type": "array", "items": { "$ref": "#/components/schemas/ProrationEvent" } }, "pro_rata_remaining_value": { "type": "integer", "format": "int64", "description": "The pro-rated remaining value for the billing period", "example": 500 } } }, "ProrationEvent": { "required": [ "proration_policy_id", "billing_cost_before_proration", "refunded_amount_for_unused_pricing_option", "new_pricing_option_cost", "prorated_at" ], "properties": { "proration_policy_id": { "$ref": "#/components/schemas/UUID" }, "billing_cost_before_proration": { "type": "integer", "format": "int64", "description": "The value as a whole number of the currency's smallest subdivision", "example": 100 }, "refunded_amount_for_unused_pricing_option": { "type": "integer", "format": "int64", "description": "The value as a whole number of the currency's smallest subdivision.", "example": 100 }, "new_pricing_option_cost": { "type": "integer", "format": "int64", "description": "The value as a whole number of the currency's smallest subdivision.", "example": 100 }, "prorated_at": { "description": "The date and time the subscription was prorated.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "SubscriptionInvoicePaymentRefund": { "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentRefundType" }, "attributes": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentRefundAttributes" }, "relationships": { "$ref": "#/components/schemas/Relationships" } } }, "SubscriptionInvoicePaymentRefundAttributes": { "required": [ "amount", "reason", "gateway", "external_refund_id", "created_at" ], "properties": { "amount": { "type": "integer", "format": "int64", "minimum": 1, "description": "The value as a whole number of the currency's smallest subdivision.", "example": 100 }, "reason": { "type": "string", "maxLength": 1024, "description": "The reason or note for the refund", "example": "Customer requested cancellation" }, "gateway": { "type": "string", "maxLength": 1024, "example": "elastic_path_payments_stripe", "description": "Specifies the payment gateway." }, "external_refund_id": { "type": "string", "maxLength": 1024, "example": "33e7ec6b-8b34-4c92-a95b-2e2647922e47", "description": "An optional external ID that is specific to the gateway used." }, "created_at": { "description": "The date and time a resource was created.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "CreateInvoicePaymentRefund": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionInvoicePaymentRefundType" }, "attributes": { "type": "object", "required": [ "amount", "reason" ], "properties": { "amount": { "type": "integer", "format": "int64", "minimum": 1, "description": "The value as a whole number of the currency's smallest subdivision.", "example": 100 }, "reason": { "type": "string", "minLength": 1, "maxLength": 1024, "description": "The reason or note for the refund", "example": "Customer requested cancellation" } } } } }, "InvoiceTimestamps": { "allOf": [ { "$ref": "#/components/schemas/Timestamps" }, { "properties": { "taxes_added_at": { "description": "The date and time taxes were added to an invoice.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } } ] }, "SubscriptionInvoicePaymentMeta": { "readOnly": true, "required": [ "owner", "timestamps", "invoice_id", "subscription_id", "job_id", "manual_payment" ], "properties": { "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "subscription_id": { "$ref": "#/components/schemas/UUID" }, "invoice_id": { "$ref": "#/components/schemas/UUID" }, "job_id": { "$ref": "#/components/schemas/UUID" }, "timestamps": { "$ref": "#/components/schemas/InvoicePaymentTimestamps" }, "manual_payment": { "type": "boolean", "example": false, "description": "Whether manual payments are enabled or the payment will be handled by the configured gateway." } } }, "InvoicePaymentTimestamps": { "allOf": [ { "$ref": "#/components/schemas/Timestamps" }, { "properties": { "payment_taken_at": { "description": "The date and time a payment was taken.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } } ] }, "SubscriptionInvoiceAttributes": { "required": [ "billing_period", "pro_forma", "invoice_items", "outstanding", "tax_required", "payment_retries_limit_reached", "manual_payment_pending" ], "properties": { "billing_period": { "$ref": "#/components/schemas/TimePeriod" }, "invoice_items": { "type": "array", "items": { "$ref": "#/components/schemas/SubscriptionInvoiceItem" } }, "tax_items": { "type": "array", "items": { "$ref": "#/components/schemas/TaxItem" } }, "outstanding": { "type": "boolean", "description": "The invoice still requires payment if `true`.", "example": true }, "number": { "type": "integer", "description": "A sequential number assigned by the billing run.", "example": 1 }, "tax_required": { "type": "boolean", "description": "Whether tax is required for this invoice.", "example": true }, "payment_retries_limit_reached": { "type": "boolean", "description": "Whether the limit of payment retries has been reached.", "example": false }, "updated_at": { "description": "The date and time an invoice was updated.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "created_at": { "description": "The date and time an invoice was created.", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "pro_forma": { "description": "Whether the invoice is a Pro Forma invoice (generated ahead of payment) or not.\n\nPro Forma Invoices are created ahead of payment time (for example, a week in advance of payment so\nyou can notify customers) and will not be picked up by a payment run until on or after their valid_from\ndate.\n", "type": "boolean", "example": false }, "valid_from": { "description": "The date and time at which an invoice will be valid from.\n\nIf generated with no lead time then the invoice will be valid immediately.\n\nIf generated with a lead time, then the valid_from will be the data at which the Invoice transitions from\nit's Pro Forma state to one that can have payment taken.\n", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "manual_payment_pending": { "type": "boolean", "description": "Whether there is a manual pending payment pending on the invoice.", "example": true } } }, "SubscriptionInvoicePaymentAttributes": { "required": [ "success", "amount", "gateway" ], "properties": { "success": { "type": "boolean", "example": true, "description": "Whether the payment was successful." }, "pending": { "type": "boolean", "example": true, "description": "Whether the payment is pending (only for manual payments)." }, "gateway": { "type": "string", "maxLength": 1024, "example": "elastic_path_payments_stripe", "description": "Specifies the payment gateway." }, "external_payment_id": { "type": "string", "maxLength": 1024, "example": "33e7ec6b-8b34-4c92-a95b-2e2647922e47", "description": "An optional external ID that is specific to the gateway used." }, "failure_detail": { "$ref": "#/components/schemas/PaymentFailureDetail" }, "amount": { "$ref": "#/components/schemas/SingleCurrencyPrice" } } }, "PaymentFailureDetail": { "type": "object", "description": "The reason the payment failed.", "properties": { "reason": { "type": "string", "example": "Card Failure" } } }, "SubscriptionInvoiceItem": { "required": [ "description", "price" ], "properties": { "description": { "type": "string", "description": "A description of the subscribed item.", "example": "Magazine issue" }, "price": { "$ref": "#/components/schemas/SingleCurrencyPrice" }, "plan_id": { "$ref": "#/components/schemas/UUID" }, "from_time_period": { "description": "The start date and time of the billing period in this price", "type": "string", "example": "2017-01-10T11:41:19.244842Z" }, "until_time_period": { "description": "The end date and time of the billing period in this price", "type": "string", "example": "2017-01-10T11:41:19.244842Z" } } }, "ErrorResponse": { "required": [ "errors" ], "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/Error" } } } }, "Error": { "required": [ "status", "title" ], "properties": { "status": { "type": "string", "description": "The HTTP response code of the error.", "example": "500" }, "title": { "type": "string", "description": "A brief summary of the error.", "example": "Internal server error" }, "detail": { "type": "string", "description": "Optional additional detail about the error.", "example": "An internal error has occurred." }, "meta": { "type": "object", "description": "Additional supporting meta data for the error.", "example": { "missing_ids": [ "e7d50bd5-1833-43c0-9848-f9d325b08be8" ] } } } }, "CurrencyIdentifier": { "type": "string", "description": "The three-letter [**ISO currency code**](https://www.iso.org/iso-4217-currency-codes.html) in uppercase.", "maxLength": 1024, "example": "USD" }, "UUID": { "type": "string", "description": "The unique identifier.", "format": "uuid", "x-go-type": "uuid.UUID", "x-go-type-import": { "name": "uuid", "path": "github.com/google/uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, "OwnerMeta": { "readOnly": true, "type": "string", "format": "string", "description": "The owner of a resource, either `store` or `organization`.", "example": "store" }, "OfferingPlanExternalRefMeta": { "readOnly": true, "type": "string", "format": "string", "description": "The offerings plan external_ref value", "example": "97dddc65-eabd-45d8-b45b-2ece5cfc8c50" }, "Subscriber": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionSubscriberType" }, "attributes": { "$ref": "#/components/schemas/SubscriberResponseAttributes" }, "meta": { "$ref": "#/components/schemas/SubscriberMeta" } } }, "SubscriberMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "feature_entitlements": { "type": "array", "description": "A list of entitlement tags currently active for the subscriber", "example": [ "tag1", "tag2" ], "items": { "$ref": "#/components/schemas/FeatureTag" } }, "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "SubscriptionSubscriberType": { "type": "string", "example": "subscription_subscriber", "enum": [ "subscription_subscriber" ] }, "SubscriberResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/SubscriberAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "SubscriberAttributes": { "required": [ "name", "email", "account_id" ], "properties": { "account_id": { "$ref": "#/components/schemas/UUID" }, "name": { "type": "string", "description": "The name of the subscriber.", "minLength": 3, "maxLength": 1024, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the subscriber.", "minLength": 3, "maxLength": 1024, "example": "john.doe@example.com", "x-go-type": "types.Email", "x-go-type-import": { "name": "email", "path": "github.com/oapi-codegen/runtime/types" } }, "payment_authority": { "$ref": "#/components/schemas/PaymentAuthority" } } }, "SubscriberUpdateAttributes": { "properties": { "name": { "type": "string", "description": "The name of the subscriber.", "minLength": 3, "maxLength": 1024, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "The email of the subscriber.", "minLength": 3, "maxLength": 1024, "example": "john.doe@example.com", "x-go-type": "types.Email", "x-go-type-import": { "name": "email", "path": "github.com/oapi-codegen/runtime/types" } }, "payment_authority": { "$ref": "#/components/schemas/NullablePaymentAuthority" } } }, "SubscriberCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionSubscriberType" }, "attributes": { "$ref": "#/components/schemas/SubscriberAttributes" } } }, "SubscriberUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionSubscriberType" }, "attributes": { "$ref": "#/components/schemas/SubscriberUpdateAttributes" } } }, "ScheduleCreate": { "required": [ "type", "attributes" ], "properties": { "type": { "$ref": "#/components/schemas/SubscriptionScheduleType" }, "attributes": { "$ref": "#/components/schemas/ScheduleAttributes" } } }, "Schedule": { "required": [ "type", "attributes", "meta" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionScheduleType" }, "attributes": { "$ref": "#/components/schemas/ScheduleResponseAttributes" }, "meta": { "$ref": "#/components/schemas/ScheduleMeta" } } }, "ScheduleMeta": { "readOnly": true, "required": [ "owner", "timestamps" ], "properties": { "scheduled_for": { "type": "string", "format": "date-time", "example": "2017-07-21T17:32:28Z" }, "owner": { "$ref": "#/components/schemas/OwnerMeta" }, "timestamps": { "$ref": "#/components/schemas/Timestamps" } } }, "SubscriptionScheduleType": { "type": "string", "example": "subscription_schedule", "enum": [ "subscription_schedule" ] }, "ScheduleResponseAttributes": { "allOf": [ { "$ref": "#/components/schemas/ScheduleAttributes" }, { "$ref": "#/components/schemas/Timestamps" } ] }, "ScheduleAttributes": { "required": [ "specification", "location", "job" ], "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRef" }, "name": { "type": "string", "description": "The name of the schedule.", "minLength": 3, "maxLength": 1024, "example": "Daily billing run." }, "specification": { "type": "string", "description": "A cron-style specification of when the jobs should be created. See [**Schedules**](/docs/api/subscriptions/schedules).", "maxLength": 1024, "example": "30 0 * * *" }, "location": { "type": "string", "description": "The location of the time zone that the schedule operates in. Subscriptions runs on Coordinated Universal Time (UTC) time and conforms to [**RFC 3339**](https://www.rfc-editor.org/rfc/rfc3339).", "maxLength": 1024, "example": "Europe/London" }, "job": { "$ref": "#/components/schemas/ScheduleJob" } } }, "ScheduleUpdateAttributes": { "properties": { "external_ref": { "$ref": "#/components/schemas/ExternalRefUpdate" }, "name": { "type": "string", "description": "The name of the schedule.", "minLength": 3, "maxLength": 1024, "example": "Daily billing run.", "nullable": true }, "specification": { "type": "string", "description": "A cron-style specification of when the jobs should be created.", "maxLength": 1024, "example": "30 0 * * *" }, "location": { "type": "string", "description": "The location of the time zone that the schedule operates in.", "maxLength": 1024, "example": "Europe/London" }, "job": { "$ref": "#/components/schemas/ScheduleJob" } } }, "ScheduleJob": { "required": [ "job_type" ], "properties": { "job_type": { "$ref": "#/components/schemas/ScheduleJobType" } } }, "ScheduleUpdate": { "required": [ "id", "type", "attributes" ], "properties": { "id": { "$ref": "#/components/schemas/UUID" }, "type": { "$ref": "#/components/schemas/SubscriptionScheduleType" }, "attributes": { "$ref": "#/components/schemas/ScheduleUpdateAttributes" } } }, "LeadTime": { "type": "object", "description": "Configuration of the lead time to generate an invoice ahead of time in a pro-forma state", "properties": { "type": { "type": "string", "description": "The unit of time that lead time is measured in.", "example": "day", "enum": [ "day", "week" ], "x-go-type": "model.LeadTimeType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "time": { "type": "integer", "description": "The lead time to generate an invoice ahead of time in a pro-forma state", "example": 14, "minimum": 1 } }, "required": [ "type", "time" ] }, "NullableLeadTime": { "type": "object", "description": "Configuration of the lead time to generate an invoice ahead of time in a pro-forma state", "nullable": true, "properties": { "type": { "type": "string", "description": "The unit of time that lead time is measured in.", "example": "week", "enum": [ "day", "week" ], "x-go-type": "model.LeadTimeType", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "time": { "type": "integer", "description": "The lead time to generate an invoice ahead of time in a pro-forma state", "example": 14, "minimum": 1 } }, "required": [ "type", "time" ] }, "NotificationSchedule": { "type": "object", "required": [ "name", "unit", "amount" ], "properties": { "name": { "type": "string", "description": "The name of the schedule.", "minLength": 1, "maxLength": 1024, "example": "Daily billing run." }, "unit": { "type": "string", "description": "The unit of time that the schedule is measured in.", "example": "day", "enum": [ "day", "week", "month" ], "x-go-type": "model.NotificationScheduleUnit", "x-go-type-import": { "name": "model", "path": "gitlab.elasticpath.com/commerce-cloud/subscriptions.svc/internal/domain/model" } }, "amount": { "type": "integer", "format": "int64", "description": "The number of units between each notification.", "example": 100, "minimum": 1 } } } } }