Skip to main content

CreateSubscriptionRequest

amountint32required

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD).

Example: 110
currencyPayment-Currency (string)required

Three-letter ISO currency code, in uppercase. Must be a supported currency.

Example: EUR
intervalSubscription-Interval (string)required

Subscription interval.

Enum ValueDescription
dayDaily
weekWeekly
monthMonthly
yearYearly

Possible values: [day, week, month, year]

Example: month
intervalCountint32

Number of intervals between subscription payments.

Example: 1
descriptionSubscription-Description (string)

An arbitrary string attached to the subscription. Often useful for displaying to users.

Example: MoonMail Monthly Lite
customer object
emailstring

The customer's email address.

Example: john.doe@example.com
namestring

The customer's full name or business name.

Example: John Doe
phonestring

The customer's phone number in E.164 format.

Example: null
billingDetails object

Billing information associated with the payment method at the time of the transaction.

namestring

The customer's billing full name.

Example: John Doe
emailstring

The customer's billing email address.

Example: john.doe@example.com
phonestring

The customer's billing phone number in E.164 format.

Example: null
companystring

Billing company name.

Example: null
taxIdstring

Company tax ID.

Example: null
address object
countryCountry (string)

Two-letter country code (ISO 3166-1 alpha-2).

Example: ES
citystring

City, district, suburb, town, or village.

Example: Málaga
line1string

Address line 1 (e.g., street, PO Box, or company name).

Example: Fake Street 123
line2string

Address line 2 (e.g., apartment, suite, unit, or building).

Example: null
zipstring

ZIP or postal code.

Example: 1234
statestring

State, county, province, or region.

Example: Málaga
shippingDetails object

Shipping information associated with the payment.

namestring

The shipping customer's full name.

Example: John Doe
emailstring

The shipping customer's email address.

Example: john.doe@example.com
phonestring

The shipping customer's phone number in E.164 format.

Example: null
companystring

Name of the company where the shipment is going.

Example: null
taxIdstring

Company tax ID.

Example: null
address object
countryCountry (string)

Two-letter country code (ISO 3166-1 alpha-2).

Example: ES
citystring

City, district, suburb, town, or village.

Example: Málaga
line1string

Address line 1 (e.g., street, PO Box, or company name).

Example: Fake Street 123
line2string

Address line 2 (e.g., apartment, suite, unit, or building).

Example: null
zipstring

ZIP or postal code.

Example: 1234
statestring

State, county, province, or region.

Example: Málaga
trialPeriodEndint64

The end date of the trial period. Measured in seconds since the Unix epoch.

Example: 1636366897
trialPeriodDaysint32

Number of days the trial period lasts.

Example: 7
retrySchedule object[]

Defines a custom schedule for retrying failed subscription payments. Each entry in the array specifies how long to wait before attempting the next payment retry. If not specified, the system's default retry schedule will be used.

  • Array [
    • intervalstringrequired

    The unit of time to wait before the retry attempt.

    Enum ValueDescription
    dayDaily
    weekWeekly
    monthMonthly
    yearYearly

    Possible values: [day, week, month, year]

    Example: day
    intervalCountint32required

    The number of intervals to wait before the retry attempt.

    Possible values: >= 1 and <= 31

    Example: 3
  • ]
    • callbackUrlSubscription-CallbackUrl (string)

    The URL will be called each time subscription status changes. You will receive a subscription object in the body of the request.

    Example: https://example.com/subscriptions/callback
    paymentCallbackUrlSubscription-PaymentCallbackUrl (string)

    The URL will be called each time subscription creates a new payments. You will receive the payment object in the body of the request.

    Example: https://example.com/payments/callback
    metadataobject

    A set of key-value pairs that you can attach to a resource. This can be useful for storing additional information about the resource in a structured format.

    Example: {"systemId":"12345"}
    CreateSubscriptionRequest
    {
      "amount": 110,
      "currency": "EUR",
      "interval": "month",
      "intervalCount": 1,
      "description": "MoonMail Monthly Lite",
      "customer": {
        "email": "john.doe@example.com",
        "name": "John Doe",
        "phone": null
      },
      "billingDetails": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": null,
        "company": null,
        "taxId": null,
        "address": {
          "country": "ES",
          "city": "Málaga",
          "line1": "Fake Street 123",
          "line2": null,
          "zip": "1234",
          "state": "Málaga"
        }
      },
      "shippingDetails": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": null,
        "company": null,
        "taxId": null,
        "address": {
          "country": "ES",
          "city": "Málaga",
          "line1": "Fake Street 123",
          "line2": null,
          "zip": "1234",
          "state": "Málaga"
        }
      },
      "trialPeriodEnd": 1636366897,
      "trialPeriodDays": 7,
      "retrySchedule": [
        {
          "interval": "day",
          "intervalCount": 1
        },
        {
          "interval": "day",
          "intervalCount": 3
        },
        {
          "interval": "week",
          "intervalCount": 1
        }
      ],
      "callbackUrl": "https://example.com/subscriptions/callback",
      "paymentCallbackUrl": "https://example.com/payments/callback",
      "metadata": {
        "systemId": "12345"
      }
    }