Create External Invoice

Create an external invoice

POST/external_subscriptions/{external_subscription_id}/external_invoices

Use it in a workflow

Add a step and choose the Recurly connector.
Pick the Create External Invoice action (under external_invoices).
Fill in the fields below, then reference the result from later steps as {{createExternalInvoice.response.data}}.

Request

Path parameters

external_subscription_idstringrequired

External subscription id

Request body

Enter the body as JSON in the step's Body field.

external_idstringrequired

An identifier which associates the external invoice to a corresponding object in an external platform.

statestringrequired

One ofpaid

totalstring (decimal)required

currencystringrequired

3-letter ISO 4217 currency code.

purchased_atstring (date-time)required

When the invoice was created in the external platform.

line_itemsarray<object>

currencystringrequired

3-letter ISO 4217 currency code.

unit_amountstring (decimal)required

quantityintegerrequired

descriptionstring

external_product_referenceany

external_payment_phaseobject

started_atstring (date-time)

ends_atstring (date-time)

starting_billing_period_indexinteger

ending_billing_period_indexinteger

offer_typestring

Type of discount offer given, e.g. "FREE_TRIAL"

offer_namestring

Name of the discount offer given, e.g. "introductory"

period_countinteger

Number of billing periods

period_lengthstring

Billing cycle length

amountstring (decimal)

Allows up to 9 decimal places

currencystring

3-letter ISO 4217 currency code.

external_payment_phase_idstring

External payment phase ID, e.g. `a34ypb2ef9w1`.

json

{
  "external_id": "string",
  "state": "paid",
  "total": "string",
  "currency": "string",
  "purchased_at": "2025-01-01T00:00:00Z",
  "line_items": [
    {
      "currency": "string",
      "unit_amount": "string",
      "quantity": 0,
      "description": "string",
      "external_product_reference": null
    }
  ],
  "external_payment_phase": {
    "started_at": "2025-01-01T00:00:00Z",
    "ends_at": "2025-01-01T00:00:00Z",
    "starting_billing_period_index": 0,
    "ending_billing_period_index": 0,
    "offer_type": "string",
    "offer_name": "string",
    "period_count": 0,
    "period_length": "string",
    "amount": "string",
    "currency": "string"
  },
  "external_payment_phase_id": "string"
}

Response

Returns 201 with an object. Read it in later steps with {{createExternalInvoice.response.data.<field>}}.

idstring

System-generated unique identifier for an external invoice ID, e.g. `e28zov4fw0v2`.

objectstring

accountobject

idstring

objectstring

codestring

The unique identifier of the account.

emailstring (email)

The email address used for communicating with this customer.

first_namestring

last_namestring

companystring

parent_account_idstring

bill_tostring

dunning_campaign_idstring

Unique ID to identify a dunning campaign. Used to specify if a non-default dunning campaign should be assigned to this account. For sites without multiple dunning campaigns enabled, the default dunning campaign will always be used.

external_subscriptionobject

Subscription from an external resource such as Apple App Store or Google Play Store.

idstring

System-generated unique identifier for an external subscription ID, e.g. `e28zov4fw0v2`.

objectstring

accountobject10 fields

external_product_referenceobject6 fields

External Product Reference details

external_payment_phasesarray<object>14 fields

The phases of the external subscription payment lifecycle.

external_idstring

The id of the subscription in the external systems., I.e. Apple App Store or Google Play Store.

uuidstring

Universally Unique Identifier created automatically.

last_purchasedstring (date-time)

When a new billing event occurred on the external subscription in conjunction with a recent billing period, reactivation or upgrade/downgrade.

auto_renewboolean

An indication of whether or not the external subscription will auto-renew at the expiration date.

Default false

in_grace_periodboolean

An indication of whether or not the external subscription is in a grace period.

Default false

app_identifierstring

Identifier of the app that generated the external subscription.

quantityinteger

An indication of the quantity of a subscribed item's quantity.

Default 1

statestring

External subscriptions can be active, canceled, expired, past_due, voided, revoked, or paused.

Default "active"

activated_atstring (date-time)

When the external subscription was activated in the external platform.

canceled_atstring (date-time)

When the external subscription was canceled in the external platform.

expires_atstring (date-time)

When the external subscription expires in the external platform.

trial_started_atstring (date-time)

When the external subscription trial period started in the external platform.

trial_ends_atstring (date-time)

When the external subscription trial period ends in the external platform.

testboolean

An indication of whether or not the external subscription was purchased in a sandbox environment.

Default false

importedboolean

An indication of whether or not the external subscription was created by a historical data import.

Default false

created_atstring (date-time)

When the external subscription was created in Recurly.

updated_atstring (date-time)

When the external subscription was updated in Recurly.

external_idstring

An identifier which associates the external invoice to a corresponding object in an external platform.

statestring

One ofpaid

totalstring (decimal)

currencystring

3-letter ISO 4217 currency code.

line_itemsarray<object>

idstring

System-generated unique identifier for an external charge ID, e.g. `e28zov4fw0v2`.

objectstring

accountobject10 fields

currencystring

3-letter ISO 4217 currency code.

unit_amountstring (decimal)

quantityinteger

descriptionstring

external_product_referenceobject6 fields

External Product Reference details

created_atstring (date-time)

When the external charge was created in Recurly.

updated_atstring (date-time)

When the external charge was updated in Recurly.

purchased_atstring (date-time)

When the invoice was created in the external platform.

created_atstring (date-time)

When the external invoice was created in Recurly.

updated_atstring (date-time)

When the external invoice was updated in Recurly.

json

{
  "id": "string",
  "object": "string",
  "account": {
    "id": "string",
    "object": "string",
    "code": "string",
    "email": "name@example.com",
    "first_name": "string",
    "last_name": "string",
    "company": "string",
    "parent_account_id": "string",
    "bill_to": "string",
    "dunning_campaign_id": "string"
  },
  "external_subscription": {
    "id": "string",
    "object": "string",
    "account": {
      "id": "string",
      "object": "string",
      "code": "string",
      "email": "name@example.com",
      "first_name": "string",
      "last_name": "string",
      "company": "string",
      "parent_account_id": "string",
      "bill_to": "string",
      "dunning_campaign_id": "string"
    },
    "external_product_reference": {
      "id": "string",
      "object": "string",
      "reference_code": "string",
      "external_connection_type": "string",
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    },
    "external_payment_phases": [
      {
        "id": "string",
        "object": "string",
        "started_at": "2025-01-01T00:00:00Z",
        "ends_at": "2025-01-01T00:00:00Z",
        "starting_billing_period_index": 0,
        "ending_billing_period_index": 0,
        "offer_type": "string",
        "offer_name": "string",
        "period_count": 0,
        "period_length": "string",
        "amount": "string",
        "currency": "string"
      }
    ],
    "external_id": "string",
    "uuid": "string",
    "last_purchased": "2025-01-01T00:00:00Z",
    "auto_renew": false,
    "in_grace_period": false,
    "app_identifier": "string",
    "quantity": 1
  },
  "external_id": "string",
  "state": "paid",
  "total": "string",
  "currency": "string",
  "line_items": [
    {
      "id": "string",
      "object": "string",
      "account": {
        "id": "string",
        "object": "string",
        "code": "string",
        "email": "name@example.com",
        "first_name": "string",
        "last_name": "string",
        "company": "string",
        "parent_account_id": "string",
        "bill_to": "string",
        "dunning_campaign_id": "string"
      },
      "currency": "string",
      "unit_amount": "string",
      "quantity": 0,
      "description": "string",
      "external_product_reference": {
        "id": "string",
        "object": "string",
        "reference_code": "string",
        "external_connection_type": "string",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-01-01T00:00:00Z"
      },
      "created_at": "2025-01-01T00:00:00Z",
      "updated_at": "2025-01-01T00:00:00Z"
    }
  ],
  "purchased_at": "2025-01-01T00:00:00Z",
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Need more? See the Recurly guide for connection setup and behaviour shared by every action.

Was this page helpful?