EasyflowEasyflowDocs

Create subscription

POST/subscriptions

Creates a subscription without an offer and charges its first recurrence on the buyer's credit card.

  • Tokenize the card with the Easyflow JavaScript SDK and send the token in creditCard.token. The token goes only in this request: no response and no webhook returns it. The next recurrences are charged to the card saved in the subscription, without a new token.
  • The API key must have write access to subscriptions, and its user must be a collaborator of the business sent in business-id.
  • Every recurrence charges valueInCents, the first one included. The first recurrence is charged by an order created with the subscription. Its orderId comes in the response.
  • The subscription starts as inactive. It becomes active when the first order is paid. If the first order is refused, the subscription is canceled and no other recurrence is charged. The response can already bring canceled, and a retry with the same idempotency-key brings the current status, which can be active.

Idempotency:

  • Send the idempotency-key header in every request. Retrying with the same key and the same body returns the same subscription and never charges twice.
  • The body is compared after removing fields with null values. buyer.device is not compared, buyer.email is compared in lowercase, and the card token is part of the comparison. The same key with a different body returns 409.
  • While another request with the same key is still running, the API returns 409. Retry later with the same key and body.
  • After a 500, or a 422 with errorCode SUBSCRIPTION_CARD_PAYMENT_SERVICE_UNAVAILABLE, retry with the same key and body.
  • When the card is refused (any other errorCode in 422), every retry with that key returns the same 422. To try another card, use a new key.

Metadata:

  • The items of metadata are copied to the first order. Easyflow also writes the keys subscription-creation-request-id, subscription-terms, ip, fingerprint-id and user-agent to that order, so these keys are reserved. subscription-terms holds, as a JSON string, the name, valueInCents, periodicity, numberRecurrences, repeatIndefinitely, retry and invoiceDescription of the subscription. Sending one of them (compared without leading and trailing spaces and ignoring case) returns 400 with Invalid param: [metadata].

Split with other businesses:

  • commissionedParticipants is optional. Send it to split the subscription with other businesses. Each item has the commissionedId of a business that receives a part, and exactly one of commissionedValueInCents (a fixed value, in cents) and commissionedPercentage (a percentage).
  • The participants receive their part in every recurrence, the first one included, with the same value or percentage sent at creation. The business sent in business-id, which owns the subscription, receives the rest.
  • The sum of the fixed values and of the percentages applied to valueInCents cannot exceed 60% of valueInCents. For example, with valueInCents equal to 4990, the parts can add up to 2994. In the request example, two businesses other than the owner receive a part: one receives 10% and the other a fixed 500, which add up to 999. The amount paid to each business in a recurrence is calculated by Easyflow with the same split rules used for orders.
  • The participants cannot be changed after the subscription is created. The API has no endpoint to add, remove or change them.
  • The response and Get subscription do not return the participants. The subscription webhook lists in participants, and the order webhook lists in the participants of each item, only the id and name of each business, without its part.
  • Invalid participants are refused with 400 before the idempotency-key is used, so you can fix the body and retry with the same key. The messages are listed in the 400 response.

Limits:

  • Up to 30 requests per minute for each user (all API keys of the same user share the limit). Above that, the API returns 429 with the Retry-After header.

Headers

  • x-api-keystringrequired

    Api key provided on integrations tab in Easyflow platform.

  • x-api-secretstringrequired

    Api Secret provided on integrations tab in Easyflow platform.

  • business-idstringrequired

    Identifier of the business the request refers to. The user of your API key must be linked to this business, as explained in The business identifier. A value that is not a business identifier returns 400 with Invalid param: [businessId], and a business that the user is not linked to returns 403.

  • idempotency-keystringrequired

    Key chosen by you that identifies the request. Send the same key when you retry the same request. It must have 1 to 255 characters after leading and trailing spaces are removed.

    min length 1max length 255

Request bodyrequired

Content typeapplication/jsonobject

  • namestringrequired

    Name of the subscription. It is also the description of the item of the first order. It cannot be empty or contain only spaces.

  • valueInCentsintegerrequired

    Value charged in every recurrence, the first one included, in cents. It must be equal to or greater than the minimum charge value of the platform (by default, 1000).

  • periodicitystringrequired

    Interval between recurrences.

    Possible values:MonthlyQuarterlyBiannualyAnnualy

  • repeatIndefinitelybooleanrequired

    When true, the subscription has no end and numberRecurrences must be omitted, null or 0.

  • numberRecurrencesintegernullable

    Total number of recurrences, the first one included. Required, as an integer from 1 to 1200, when repeatIndefinitely is false. When repeatIndefinitely is true, omit it or send null or 0.

    <= 1200

  • retryobject

    How Easyflow retries a failed recurrence. When omitted, it makes 5 attempts every 3 days. When sent, it must be an object (otherwise the API returns 400 with Invalid param: [retry]) and both fields are required.

    Show child attributesHide child attributes
    • retriesMaxNumberintegerrequired

      Maximum number of attempts.

      >= 1<= 10

    • intervalInDaysintegerrequired

      Days between attempts.

      >= 1<= 15

  • buyerobjectrequired

    Buyer who pays the subscription.

    Show child attributesHide child attributes
    • namestringrequired
    • emailstringrequired

      E-mail of the buyer. It is stored in lowercase.

    • phoneobjectrequired
      Show child attributesHide child attributes
      • areaCodestring

        Country code with +, such as +55.

      • dddstring

        Area code with 2 digits, such as 11.

      • numberstring

        Phone number with 8 or 9 digits.

      • isMobileboolean
    • documentobjectrequired
      Show child attributesHide child attributes
      • typestring

        Possible values:CPFCNPJ

      • numberstring

        Document number with digits only.

    • addressobject
      Show child attributesHide child attributes
      • zipCodestring

        Zip code with digits only, such as 01310100.

      • streetstring
      • numberstring
      • complementstring
      • neighborhoodstring
      • citystring
      • statestring

        State code with 2 letters, such as SP.

    • deliveryAddressobject
      Show child attributesHide child attributes
      • zipCodestring

        Zip code with digits only, such as 01310100.

      • streetstring
      • numberstring
      • complementstring
      • neighborhoodstring
      • citystring
      • statestring

        State code with 2 letters, such as SP.

    • deviceobjectrequired

      Device of the buyer, sent with the card. When the subscription is created, it is also written to the metadata of the first order.

      Show child attributesHide child attributes
      • ipstringrequired

        IP address of the buyer. Never send the IP address of your server.

      • fingerprintIdstringrequired

        Fingerprint of the device of the buyer.

      • userAgentstringrequired

        User agent of the browser of the buyer.

  • creditCardobjectrequired

    Credit card of the buyer. The card number is sent only inside token, created with the Easyflow JavaScript SDK.

    Show child attributesHide child attributes
    • tokenstringrequired

      Encrypted card token returned by the Easyflow JavaScript SDK. Sent only in this request. No response and no webhook returns it.

    • last4Numbersstringrequired

      Last 4 digits of the card.

    • holderNamestringrequired

      Name printed on the card.

    • expiresAtMonthintegerrequired

      Expiration month of the card.

    • expiresAtYearintegerrequired

      Expiration year of the card.

    • flagstringrequired

      Card brand.

      Possible values:visamastercardamerican-expressdiners-clubdiscoverjcbunionpaymaestromirelohiperhipercard

  • commissionedParticipantsarray of objects

    Optional. Businesses that receive a part of every recurrence, the first one included. The business sent in business-id receives the rest. The sum of the fixed values and of the percentages applied to valueInCents cannot exceed 60% of valueInCents; otherwise the API returns 400 with Invalid param: [commissionedParticipants.commission]. When sent, it must be a list of objects; otherwise the API returns 400 with Invalid param: [commissionedParticipants]. The participants cannot be changed after the subscription is created.

    Show child attributesHide child attributes
    • commissionedIdstring · uuidrequired

      ID of the business that receives this part. When it is missing or is not a valid ID, the API returns 400 with Invalid param: [commissionedId]. When no business has this ID, the API returns 400 with Invalid param: [invalid commissionedId: <id>].

    • commissionedValueInCentsintegernullable

      Fixed part of each recurrence, in cents. It must be an integer equal to or greater than 1; otherwise the API returns 400 with Invalid param: [commissionedParticipants.commissionedValueInCents].

      >= 1

    • commissionedPercentagenumbernullable

      Part of each recurrence as a percentage, such as 10 for 10%. It must be a number greater than 0 and can have decimals; otherwise the API returns 400 with Invalid param: [commissionedParticipants.commissionedPercentage]. For the 60% limit, it is applied to valueInCents.

      > 0

  • invoiceDescriptionstring

    Text shown on the card statement of the buyer. When omitted, Easyflow derives it from name. When it is not a string, the API returns 400 with Invalid param: [invoiceDescription].

  • metadataarray of objects

    Your own key and value pairs, copied to the first order. The keys subscription-creation-request-id, subscription-terms, ip, fingerprint-id and user-agent are reserved. When metadata is not a list, an item does not have key and value as strings, or a key is reserved, the API returns 400 with Invalid param: [metadata].

    Show child attributesHide child attributes
    • keystringrequired
    • valuestringrequired

Responses

200The subscription was created, or a retry with the same idempotency-key and body found it.

The subscription was created, or a retry with the same idempotency-key and body found it.

Content typeapplication/jsonobject

  • statusCodeinteger

    Example:200

  • dataobject
    Show child attributesHide child attributes
    • subscriptionIdstring · uuid

      ID of the subscription.

    • orderIdstring · uuid

      ID of the order that charges the first recurrence.

    • statusstring

      Status of the subscription. It is inactive until the first order is paid and canceled when the first order is refused.

      Possible values:activeinactivecanceledexpired

400A field or header is missing or invalid. The message names it, such as Missing param: [idempotency-key], Missing param: [numberRecurrences], Invalid param: [repeatIndefinitely], Invalid param: [numberRecurrences], Invalid param: [retry] or Invalid param: [retry.intervalInDays].

A field or header is missing or invalid. The message names it, such as Missing param: [idempotency-key], Missing param: [numberRecurrences], Invalid param: [repeatIndefinitely], Invalid param: [numberRecurrences], Invalid param: [retry] or Invalid param: [retry.intervalInDays].

Messages about commissionedParticipants:

  • Invalid param: [commissionedParticipants]: it is not a list, or one of its items is not an object.
  • Invalid param: [commissionedParticipants.commission]: an item has none or both of commissionedValueInCents and commissionedPercentage, or the sum of the parts exceeds 60% of valueInCents.
  • Invalid param: [commissionedParticipants.commissionedValueInCents]: the fixed value is not an integer equal to or greater than 1.
  • Invalid param: [commissionedParticipants.commissionedPercentage]: the percentage is not a number greater than 0.
  • Invalid param: [commissionedId]: the commissionedId of an item is missing or is not a valid ID.
  • Invalid param: [invalid commissionedId: <id>]: no business has this ID. <id> is the value you sent.

The errors listed here are returned before the idempotency-key is used, so you can fix the body and retry with the same key.

Content typeapplication/jsonobject

  • messagestring

    Invalid param: []

    Example:Invalid param: []

  • errorstring

    Bad Request

    Example:Bad Request

  • statusCodeinteger

    400

    Example:400

  • errorCodestring

    Code that identifies the error. Present only on some errors.

401The credential is missing or invalid, or the business-id header is missing (message BusinessId is required).

The credential is missing or invalid, or the business-id header is missing (message BusinessId is required).

Content typeapplication/jsonobject

  • messagestring

    Invalid field

    Example:Unauthorized

  • errorstring

    Unauthorized

    Example:Unauthorized

  • statusCodeinteger

    401

    Example:401

403The API key has no write access to subscriptions, or its user is not a collaborator of the business sent in business-id.

The API key has no write access to subscriptions, or its user is not a collaborator of the business sent in business-id.

Content typeapplication/jsonobject

  • messagestring

    Forbidden resource

    Example:Forbidden resource

  • errorstring

    Forbidden

    Example:Forbidden

  • statusCodeinteger

    403

    Example:403

409The idempotency-key was already used with a different body (message idempotency-key already used with a different payload), or a request with this key is still running (message subscription creation in progress, retry later with the same idempotency-key).

The idempotency-key was already used with a different body (message idempotency-key already used with a different payload), or a request with this key is still running (message subscription creation in progress, retry later with the same idempotency-key).

Content typeapplication/jsonobject

  • statusCodeintegerrequired

    HTTP status code.

  • messagestringrequired

    Explanation of the error.

  • errorstring

    Name of the HTTP status, such as Bad Request or Conflict.

  • errorCodestring

    Code that identifies the error. Present only on some errors.

422The card could not be used. The errorCode field tells why: SUBSCRIPTIONCARDINVALIDCARDTOKEN, SUBSCRIPTIONCARDCUSTOMERNOTFOUND, SUBSCRIPTIONCARDDATAUNREADABLE or SUBSCRIPTIONCARDREJECTED (the card was refused and the key returns the same error on every retry), or SUBSCRIPTIONCARDPAYMENTSERVICEUNAVAILABLE (temporary failure; retry with the same key and body).

The card could not be used. The errorCode field tells why: SUBSCRIPTION_CARD_INVALID_CARD_TOKEN, SUBSCRIPTION_CARD_CUSTOMER_NOT_FOUND, SUBSCRIPTION_CARD_DATA_UNREADABLE or SUBSCRIPTION_CARD_REJECTED (the card was refused and the key returns the same error on every retry), or SUBSCRIPTION_CARD_PAYMENT_SERVICE_UNAVAILABLE (temporary failure; retry with the same key and body).

Content typeapplication/jsonobject

  • statusCodeintegerrequired

    HTTP status code.

  • messagestringrequired

    Explanation of the error.

  • errorstring

    Name of the HTTP status, such as Bad Request or Conflict.

  • errorCodestring

    Code that identifies the error. Present only on some errors.

429More than 30 requests in a minute for the user (all API keys of the same user share the limit). The message is Too many requests, retry after the Retry-After seconds. Wait the number of seconds in the Retry-After header before sending a new request.

More than 30 requests in a minute for the user (all API keys of the same user share the limit). The message is Too many requests, retry after the Retry-After seconds. Wait the number of seconds in the Retry-After header before sending a new request.

Content typeapplication/jsonobject

  • statusCodeinteger

    HTTP status code.

    Example:429

  • messagestring

    Explanation of the error.

    Example:Too many requests, retry after the Retry-After seconds

500An unexpected error occurred. Retry with the same idempotency-key and body: the request continues from where it stopped and never charges twice.

An unexpected error occurred. Retry with the same idempotency-key and body: the request continues from where it stopped and never charges twice.

Content typeapplication/jsonobject

  • statusCodeinteger

    HTTP status code.

    Example:500

  • messagestring

    Explanation of the error.

    Example:Internal Server Error