> For the complete documentation index, see [llms.txt](https://apidocs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.akinon.com/commerce-openapis/subscription/subscriptions.md).
# Subscriptions
## Retrieve subscription form schema
> Returns the current subscription form schema configuration. This schema\
> defines the available fields, their types, validation rules, and whether\
> they are required for subscription creation.\
> \
> The schema is dynamically configured and can be updated through the\
> administration interface without requiring code deployment.
```json
{"openapi":"3.0.0","info":{"title":"Subscriptions API","version":"1.0.0"},"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/subscriptions/":{"get":{"summary":"Retrieve subscription form schema","description":"Returns the current subscription form schema configuration. This schema\ndefines the available fields, their types, validation rules, and whether\nthey are required for subscription creation.\n\nThe schema is dynamically configured and can be updated through the\nadministration interface without requiring code deployment.\n","operationId":"getSubscriptionSchema","tags":["Subscriptions"],"responses":{"200":{"description":"Successfully retrieved the subscription form schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionSchemaResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SubscriptionSchemaResponse":{"type":"object","description":"Response containing the subscription form schema configuration","required":["attributes"],"properties":{"attributes":{"type":"object","description":"Dynamic schema object where each key represents an attribute name\nand the value contains the attribute configuration including type,\nvalidation rules, and display properties.\n","additionalProperties":{"$ref":"#/components/schemas/AttributeSchema"}}}},"AttributeSchema":{"type":"object","description":"Configuration for a single subscription form attribute","properties":{"label":{"type":"string","description":"Display label for the attribute"},"data_type":{"type":"string","description":"The data type of the attribute. Common types include text, number,\nemail, dropdown, checkbox, date, and nested_object.\n","enum":["text","number","email","dropdown","checkbox","date","nested_object"]},"is_required":{"type":"boolean","description":"Indicates whether this attribute must be provided when creating\na subscription.\n","default":false},"multi":{"type":"boolean","description":"Indicates whether this attribute accepts multiple values (array)\nor a single value.\n","default":false},"is_localizable":{"type":"boolean","description":"Indicates whether this attribute supports multiple language\ntranslations.\n","default":false},"choices":{"type":"array","description":"Available options for dropdown-type attributes. Only applicable\nwhen data_type is 'dropdown'.\n","items":{"type":"object","properties":{"value":{"type":"string","description":"The option value"},"label":{"type":"string","description":"The display label for the option"}}}},"schema":{"type":"object","description":"Nested schema definition for nested_object-type attributes.\nOnly applicable when data_type is 'nested_object'.\n","additionalProperties":{"$ref":"#/components/schemas/AttributeSchema"}}}},"Error":{"type":"object","description":"Standard error response","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}}}}}}
```
## Create a new subscription
> Creates a new email subscription with the provided email address and\
> optional additional attributes defined by the subscription form schema.\
> \
> The email address must be unique. If a subscription with the same email\
> already exists, the request will be rejected.\
> \
> All required attributes as defined in the subscription form schema must\
> be provided. The system validates that all mandatory fields are present\
> before creating the subscription.
```json
{"openapi":"3.0.0","info":{"title":"Subscriptions API","version":"1.0.0"},"servers":[{"description":"Server base URL for address operations","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce server URL"}}}],"paths":{"/subscriptions/":{"post":{"summary":"Create a new subscription","description":"Creates a new email subscription with the provided email address and\noptional additional attributes defined by the subscription form schema.\n\nThe email address must be unique. If a subscription with the same email\nalready exists, the request will be rejected.\n\nAll required attributes as defined in the subscription form schema must\nbe provided. The system validates that all mandatory fields are present\nbefore creating the subscription.\n","operationId":"createSubscription","tags":["Subscriptions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequest"}}}},"responses":{"201":{"description":"Subscription created successfully","content":{"application/json":{"schema":{"type":"object","description":"Empty response body"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"409":{"description":"Email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"SubscriptionRequest":{"type":"object","description":"Request payload for creating a new subscription","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"The email address for the subscription. Must be unique across\nall subscriptions.\n"},"attributes":{"type":"object","description":"Additional subscription attributes as defined by the subscription\nform schema. The structure and required fields depend on the\ncurrent schema configuration retrieved from the GET endpoint.\n","additionalProperties":true}}},"ValidationError":{"type":"object","description":"Validation error response","properties":{"error":{"type":"string","description":"General validation error message"}},"additionalProperties":{"type":"array","items":{"type":"string"},"description":"Field-specific validation errors"}},"Error":{"type":"object","description":"Standard error response","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://apidocs.akinon.com/commerce-openapis/subscription/subscriptions.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.