> ## Documentation Index
> Fetch the complete documentation index at: https://docs.global-e.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create recurring payment (Subscription Manager to Global-e)
> Subscription Manager trigger Global-e to perform a recurring payment
Part of the [Subscription Connector](/subscription-connector) integration guide — see it for when and how to use this endpoint.
The status of the payment arrives through [Recurring payment notifications](/api-reference/recurring-payment-notifications).
## OpenAPI
````yaml api-reference/specs/recurringpayments.yaml POST /subscriptions/recurringPayments
openapi: 3.0.3
info:
title: Recurring Payment
version: '1.4'
description: >-
This endpoint allows the Subscription Manager to trigger Global-e to process
a recurring payment.
servers:
- url: https://{globale_api_domain}
variables:
globale_api_domain:
default: globale_api_domain
description: Global-e API host, supplied to the merchant by Global-e.
security: []
tags:
- name: Recurring payments
x-page-title: Create recurring payment
- name: 'Direction: Subscription Manager → Global-e'
- name: 'Domain: Payments'
paths:
/subscriptions/recurringPayments:
post:
tags:
- Recurring payments
summary: Create recurring payment
description: Subscription Manager trigger Global-e to perform a recurring payment
operationId: createRecurringPayment
parameters:
- name: Idempotency-Key
in: header
required: true
description: >-
Unique identifier for the request; the same value must be sent on
retries so the operation is applied at most once.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateRecurringPaymentRequest'
example:
subscriptionId: '123456'
merchantGuid: '1234567890'
externalReferenceId: '1234567890'
products:
- code: PROD-001
quantity: 2
price: 149.99
dtAmount: 12.75
discounts: []
payment:
totalDuties: 15.5
totalTaxes: 12.75
shippingAmount: 10
additionalFee: 5
totalAmount: 343.23
currencyCode: USD
responses:
'202':
description: Request accepted.
content:
application/json:
schema:
$ref: '#/components/schemas/Success'
examples:
accepted:
summary: Request received successfully
value:
description: Request received successfully!
'400':
description: Bad Request - Invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalid_order_id:
summary: Invalid Order ID
value:
error: Invalid OrderId format
code: INVALID_ORDER_ID
description: The provided OrderId is not in the correct format.
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
error: Invalid API Key
code: UNAUTHORIZED
description: Invalid API Key
'403':
description: Forbidden - Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
insufficient_permissions:
summary: Insufficient permissions
value:
error: Access denied
code: INSUFFICIENT_PERMISSIONS
description: User does not have permission to perform the operation.
'404':
description: Object not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
subscription_details_not_found:
summary: Subscription details not found
value:
error: Subscription details not found
code: SUBSCRIPTION_DETAILS_NOT_FOUND
description: >-
No subscription details found for the specified
subscriptionId.
product_not_found:
summary: Product not found
value:
error: Product not found
code: PRODUCT_NOT_FOUND
description: No product found for the specified code.
'409':
description: Conflict - Idempotency key conflict
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
idempotency_key_conflict:
summary: Idempotency key conflict
value:
error: Idempotency key conflict
code: IDEMPOTENCY_KEY_CONFLICT
description: >-
Request already in use. Use a different Idempotency-Key
for new operation.
'422':
description: Unprocessable Content - the request is valid but cannot be fulfilled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
no_shipping_option_available:
summary: No shipping option available
value:
error: No shipping option available
code: NO_SHIPPING_OPTION_AVAILABLE
description: >-
No shipping option could be selected for the
subscription's destination.
products_restricted:
summary: One or more products cannot be shipped to the destination
value:
error: Product restricted for destination
code: PRODUCT_RESTRICTED
description: >-
SKU-002: This product cannot be shipped to your location.
SKU-008: This product cannot be shipped to your location.
SKU-009: This product cannot be shipped to your location.
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal_error:
summary: Internal server error
value:
error: Internal server error
code: INTERNAL_ERROR
description: An unexpected error occurred while processing the request.
default:
description: General error structure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codeSamples:
- lang: curl
source: >-
curl -X POST
"https://{globale_api_domain}/subscriptions/recurringPayments" \
-H "Authorization: Bearer {JWT Token}" \
-H "Idempotency-Key: 3f1a7c2e-9b40-4d6f-8a21-5c9e0b7d4a11" \
-H "Content-Type: application/json" \
-d '{"subscriptionId":"123456","merchantGuid":"1234567890","externalReferenceId":"INV-002","products":[{"code":"PROD-001","price":149.99,"quantity":2}],"payment":{"totalDuties":15.50,"totalTaxes":12.75,"shippingAmount":10.00,"additionalFee":5.00,"totalAmount":343.23,"currencyCode":"USD"}}'
components:
schemas:
CreateRecurringPaymentRequest:
type: object
description: Represents a recurring payment creation event.
required:
- subscriptionId
- merchantGuid
- externalReferenceId
- products
- discounts
- payment
properties:
subscriptionId:
$ref: '#/components/schemas/SubscriptionId'
merchantGuid:
$ref: '#/components/schemas/MerchantGuid'
externalReferenceId:
$ref: '#/components/schemas/ExternalReferenceId'
products:
$ref: '#/components/schemas/ProductsCreateRecurring'
discounts:
$ref: '#/components/schemas/Discounts'
description: >-
Discounts applied to this cycle. The property must be present; send
an empty array when no discount applies.
payment:
$ref: '#/components/schemas/Payment'
Success:
type: object
required:
- description
properties:
description:
type: string
description: Human-readable message
ErrorResponse:
type: object
description: Error response structure
required:
- error
- code
properties:
error:
type: string
description: Human-readable error message
code:
type: string
description: >-
Machine-readable error code. Codes documented for the Subscriptions
integration:
| Code | HTTP status | Description | Typical cause |
| --- | --- | --- | --- |
| INVALID_ORDER_ID | 400 | Invalid order ID format | Malformed order
ID |
| INVALID_SUBSCRIPTION_ID | 400 | Invalid subscription ID |
Malformed subscription ID |
| INVALID_PRODUCT_CODE | 400 | Invalid product code | Unknown
product code |
| UNAUTHORIZED | 401 | Authentication failed | Invalid or missing
credentials |
| INSUFFICIENT_PERMISSIONS | 403 | Insufficient permissions | User
lacks required permissions |
| ORDER_NOT_FOUND | 404 | Order not found | Order ID doesn't exist |
| SUBSCRIPTION_NOT_FOUND | 404 | Subscription not found |
Subscription ID doesn't exist |
| SUBSCRIPTION_DETAILS_NOT_FOUND | 404 | Subscription details not
found | Details not found in Global-e |
| PRODUCT_NOT_FOUND | 404 | Product not found | Product code doesn't
exist |
| EXTERNAL_REFERENCE_NOT_FOUND | 404 | External reference not found
| Invalid externalReferenceId |
| IDEMPOTENCY_KEY_CONFLICT | 409 | Idempotency key conflict |
Duplicate idempotency key |
| NO_SHIPPING_OPTION_AVAILABLE | 422 | No shipping option available
| No shipping option for the subscription's destination |
| INVALID_ADDRESS | 422 | Shipping address failed validation |
Address failed validation on address update |
| COUNTRY_CHANGE_NOT_ALLOWED | 422 | Country change rejected | The
shipping address country cannot be changed |
| VALIDATION_FAILED | 422 | Validation failed | Missing/invalid
field |
| INTERNAL_ERROR | 500 | Internal server error | Unexpected server
error |
description:
type: string
description: Detailed error description
SubscriptionId:
type: string
maxLength: 100
description: Unique identifier of subscription in the subscription manager.
MerchantGuid:
type: string
format: uuid
description: Global-e merchant unique identifier
ExternalReferenceId:
type: string
description: >-
Unique identifier of external document object, like invoiceId in the
subscription manager
ProductsCreateRecurring:
type: array
description: List of products
minItems: 1
items:
type: object
description: All fields which describe a product
required:
- code
- price
- quantity
properties:
code:
$ref: '#/components/schemas/ProductCode'
quantity:
$ref: '#/components/schemas/ProductQuantity'
price:
$ref: '#/components/schemas/ProductPrice'
dtAmount:
$ref: '#/components/schemas/ProductDtAmount'
Discounts:
type: array
description: Applied discounts (order and product level)
items:
$ref: '#/components/schemas/Discount'
Payment:
type: object
description: >-
Payment details. For physical / hybrid subscriptions, shippingAmount is
required and is charged as-is: Global-e does not recalculate any amount
while applying payment.
required:
- totalAmount
- currencyCode
properties:
totalDuties:
type: number
format: double
description: Duties amount in customer currency
totalTaxes:
type: number
format: double
description: Taxes amount in customer currency
shippingAmount:
type: number
format: double
minimum: 0
description: Shipping price in customer currency
additionalFee:
type: number
minimum: 0
description: Additional fee like handling or clearance fee in customer currency
totalAmount:
type: number
format: double
description: Total amount in customer currency
currencyCode:
$ref: '#/components/schemas/CurrencyCode'
ProductCode:
type: string
description: Unique product identifier
ProductQuantity:
type: integer
format: int32
description: Products quantity value.
ProductPrice:
type: number
format: double
description: Product price
ProductDtAmount:
type: number
format: double
description: Products duties and taxes amount
Discount:
type: object
properties:
code:
type: string
description: Discount code
type:
type: string
enum:
- Cart
description: >-
Discount type. Only "Cart" is supported, for both cart-level and
product-level discounts; any other value is rejected with 400
VALIDATION_FAILED
amount:
type: number
format: double
description: Discount amount, greater than 0
productCode:
type: string
nullable: true
description: null for order-level, productCode for product-level
CurrencyCode:
type: string
description: ISO 4217 currency code
pattern: ^[A-Z]{3}$
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.