> For the complete documentation index, see [llms.txt](https://apidocs.onekeypayments.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidocs.onekeypayments.com/api-reference/deposits-api/manage-subscriptions/create-a-subscription-oneshot.md).

# Create a subscription (OneShot)

## Create a new subscription

> This endpoint allows the creation of a new subscription with payment details.

```json
{"openapi":"3.0.0","info":{"title":"Subscription API","version":"3.0.0"},"servers":[{"url":"https://api-stg.onekeypayments.com","description":"Staging Server"}],"paths":{"/v3/subscriptions":{"post":{"tags":["Create a Subscription"],"summary":"Create a new subscription","description":"This endpoint allows the creation of a new subscription with payment details.","operationId":"createSubscription","parameters":[{"name":"Content-Type","in":"header","description":"Media type of the body sent to the API.","required":true,"schema":{"type":"string","default":"application/json"}},{"name":"X-Date","in":"header","description":"ISO8601 Datetime with Timezone (yyyy-MM-dd'T'HH:mm:ssZ)","required":true,"schema":{"type":"string","format":"date-time"}},{"name":"X-Login","in":"header","description":"Merchant X-Login API Key.","required":true,"schema":{"type":"string"}},{"name":"Authorization","in":"header","description":"Authorization control hash.","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","description":"Unique idempotency key for ensuring that the same request is not processed more than once.","required":false,"schema":{"type":"string"}}],"requestBody":{"description":"Subscription details","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionRequest"}}}},"responses":{"200":{"description":"Subscription created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"subscription_id":{"type":"integer","description":"Unique identifier of the created subscription"},"redirect_url":{"type":"string","format":"uri","description":"URL to redirect the user to complete the subscription process"},"expiration_date":{"type":"string","format":"date-time","description":"Expiration date and time for the subscription checkout process"},"payment_amount":{"type":"number","format":"double","description":"Amount to be charged for the subscription"},"redirect":{"type":"boolean","description":"Indicates if the user should be redirected to complete the process"}}}}}},"400":{"description":"Bad Request - Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable Entity - Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Service Unavailable - Error creating subscription","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"description":{"type":"string"}}}}}}}}}},"components":{"schemas":{"SubscriptionRequest":{"type":"object","required":["invoice_id","amount","currency","country","payer","subscription"],"properties":{"invoice_id":{"type":"string","description":"Unique identifier for the invoice"},"amount":{"type":"number","format":"double","description":"Amount to be charged for the subscription"},"currency":{"type":"string","description":"Three-letter currency code (ISO 4217)"},"country":{"type":"string","description":"Two-letter country code (ISO 3166-1 alpha-2)"},"payer":{"$ref":"#/components/schemas/Payer"},"description":{"type":"string","description":"Description of the subscription"},"subscription":{"$ref":"#/components/schemas/SubscriptionDetails"},"client_ip":{"type":"string","description":"IP address of the client"},"back_url":{"type":"string","format":"uri","description":"URL to redirect after payment process"},"success_url":{"type":"string","format":"uri","description":"URL to redirect after successful payment"},"error_url":{"type":"string","format":"uri","description":"URL to redirect after failed payment"},"notification_url":{"type":"string","format":"uri","description":"URL to send payment status notifications"}}},"Payer":{"type":"object","required":["id","document","document_type","email","first_name","last_name"],"properties":{"id":{"type":"string","description":"Unique identifier for the payer"},"document":{"type":"string","description":"Payer's identification document number"},"document_type":{"type":"string","description":"Type of identification document"},"email":{"type":"string","format":"email","description":"Payer's email address"},"first_name":{"type":"string","description":"Payer's first name"},"last_name":{"type":"string","description":"Payer's last name"}}},"SubscriptionDetails":{"type":"object","required":["start_date","plan","plan_unit"],"properties":{"start_date":{"type":"string","format":"date","description":"Date when the subscription should start (YYYY-MM-DD)"},"plan":{"type":"string","description":"Frequency of the subscription (DAILY, WEEKLY, MONTHLY, ANNUALLY)","enum":["DAILY","WEEKLY","MONTHLY","ANNUALLY"]},"plan_unit":{"type":"integer","description":"Number of plan units (e.g., 1 for monthly, 3 for quarterly)"},"auto_renewal":{"type":"boolean","description":"Whether the subscription should automatically renew","default":false}}},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error code"},"description":{"type":"string","description":"Error description"},"type":{"type":"string","description":"Error type"}},"required":["code","description","type"]}}}}
```