Recurly External Invoices API
The external-invoices API from Recurly — 2 operation(s) for external-invoices.
The external-invoices API from Recurly — 2 operation(s) for external-invoices.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/recurly:recurly-external-invoices-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Recurly V2 External Invoices API
description: '# Getting Started
Welcome to the reference documentation for Recurly''s XML API v2. Here you will find a complete
reference for all API v2 operations. If you''re building a new product, or just getting started with Recurly, we recommend
using our newer JSON API v3. Now let''s get started with API v2. # Authentication
##### API Authentication (HTTP Basic)
Recurly uses HTTP Basic Authentication—your Private API key is securely encrypted by the SSL channel. If you are testing the API calls via the command line with cURL, try:
```
curl -H ''Accept: application/xml'' \
-H ''X-Api-Version: 2.29'' \
-H ''Content-Type: application/xml; charset=utf-8'' \
-u ''[apikey]'' \
https://[subdomain].recurly.com/v2/accounts
```
Replace `[apikey]` and `[subdomain]` with the appropriate values for your site. ##### Calculating your own authorization header
Most programming languages encode the authorization header automatically. With HTTP Basic Authentication, the `Authorization` header is a string containing a Base-64 encoded username and password. In the case of Recurly''s API, you need only specify the username as your API key. If your library requires a password, set it to an empty string. ```
"Authorization": "Basic " + base64_encode(API Key)
```
##### Additional Request Headers
**Accept Header**
Recurly API v2 returns results as XML. Your requests should always include the header requesting the results as XML:
```
Accept: application/xml
```
**Content-Type Header**
When sending data to Recurly in a POST or PUT request, your request must specify the content type of your request:
```
Content-Type: application/xml; charset=utf-8
```
**X-Api-Version Header**
When sending data to Recurly, your request should specify the API version you''re attempting to interact with:
```
X-Api-Version: 2.29
```
You learn more about the different versions in the API Versioning section. ##### Public API Key
Recurly uses two types of API keys: public and private. The Public API key is used by Recurly.js to identify its requests as belonging to your Recurly site. This key can be safely included in Javascript code. Recurly provides each site with one Public Key. The Public API Key can be regenerated on the API Credentials page. ##### Private API Keys
###### Treat your Private API Keys like passwords! The API key allows access to your site''s data. Do not include it in Javascript code exposed to browsers. Recurly supports the use of multiple Private API keys, which can be used to integrate third party services using unique, controlled credentials. **Limits & Pricing**
Merchants on the Starter or grandfathered Recurly plans or merchants in sandbox mode will be granted 5 private API keys. Merchants on Recurly''s Professional plan will be granted 10 private API keys. **Default Key**
Your default private API key should be used to integrate Recurly with your backend systems. There will be at least one key active at all times. **Additional Keys**
Additional private API keys should be used to connect your Recurly data to additional sources, like analytics software, accounting packages, or email tools. Recurly recommends clearly labeling the name of each key to identify the associated vendor. **Regenerating Private API Keys**
Your API key can be regenerated by clicking on the Regenerate button on the API credentials page. When you generate a private API key, you have two options:
1. Block the old key immediately. This is primarily recommended when the security of a key has been compromised. 2. Allow the old key access for 12 hours. This is primarily used when updating systems and a smooth transition between keys is needed. *If a private API key is changed, an email alert will be sent to your Recurly Site Technical Contact.*
**Read-Only Keys**
When creating a private key, you will have the option to set the key to “read-only”. This means the API key may make GET requests but cannot not PUT, POST or DELETE requests.'
version: '2.29'
servers:
- url: https://{subdomain}.{domain}/v2
variables:
subdomain:
description: Subdomain of your Recurly site.
default: my-super-successful-company
domain:
description: Domain of your Recurly site.
default: recurly.com
security:
- api_key: []
tags:
- name: external-invoices
x-displayName: External Invoices
paths:
/external_invoices:
get:
summary: Lists a Site's External Invoices
description: 'See the Pagination Guide
to learn how to use pagination in the API and Client Libraries.'
tags:
- external-invoices
operationId: listExternalInvoices
responses:
'200':
description: ''
content:
application/xml:
schema:
$ref: '#/components/schemas/ExternalInvoice'
example: "<external_invoices type=\"array\">\n <external_invoice href=\"https://your-subdomain.recurly.com/v2/external_invoices/sd28t3zdm59r\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <external_subscription href=\"https://your-subdomain.recurly.com/v2/external_subscriptions/s3q9fpcryplx\"/>\n <external_payment_phase href=\"https://your-subdomain.recurly.com/v2/external_payment_phases/tws7x821sv1z\"/>\n <external_id>external-id</external_id>\n <state>paid</state>\n <currency>USD</currency>\n <total>100</total>\n <line_items type=\"array\">\n <external_charge>\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <external_invoice href=\"https://your-subdomain.recurly.com/v2/external_invoices/sd28t3zdm59r\"/>\n <external_product_reference>\n <id>scvf0zhrsjpu</id>\n <reference_code>reference-code</reference_code>\n <external_connection_type>apple_app_store</external_connection_type>\n <created_at type=\"datetime\">2023-02-06T19:56:18Z</created_at>\n <updated_at type=\"datetime\">2023-02-06T19:56:18Z</updated_at>\n </external_product_reference>\n <description></description>\n <unit_amount>50</unit_amount>\n <currency>USD</currency>\n <quantity>1</quantity>\n <created_at>2023-01-13T17:28:02Z</created_at>\n <updated_at>2023-01-13T17:28:02Z</updated_at>\n </external_charge>\n </line_items>\n <purchased_at>2023-01-13T17:28:02Z</purchased_at>\n <created_at>2023-01-13T17:28:02Z<</created_at>\n <updated_at>2024-10-10T21:40:57Z</updated_at>\n </external_invoice>\n</external_invoices>"
x-codeSamples:
- lang: PHP
source: "<?php\n\n$external_invoices = Recurly_ExternalInvoiceList::get();\nforeach ($external_invoices as $external_invoice) {\n print \"External Invoice: $external_invoice\\n\";\n}"
- lang: Ruby
source: "Recurly::ExternalInvoice.find_each do |external_invoice|\n puts \"External Invoice: #{external_invoice.inspect}\"\nend"
- lang: Python
source: "#client version 2.1.6+\nfor external_invoice in ExternalInvoice.all():\n print 'External Invoice: %s' % external_invoice\n"
- lang: Dotnet
source: "using System.Linq;\n\nvar externalInvoices = ExternalInvoice.List();\nwhile (externalInvoices.Any())\n{\n foreach (var externalInvoice in externalInvoices)\n Console.WriteLine(\"External Invoice: \" + externalInvoice);\n externalInvoices = externalInvoices.Next;\n}"
/external_invoices/{uuid}:
get:
summary: Fetch an External Invoice
description: Returns a specific external invoice.
tags:
- external-invoices
operationId: fetchExternalInvoice
parameters:
- in: path
name: uuid
schema:
type: string
default: ''
required: true
description: The uuid for the external invoice.
responses:
'200':
description: ''
content:
application/xml:
example: "<external_invoice href=\"https://your-subdomain.recurly.com/v2/external_invoices/rpap82ntgqqh\">\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <external_subscription href=\"https://your-subdomain.recurly.com/v2/external_subscriptions/s3q9fpcryplx\"/>\n <external_payment_phase href=\"https://your-subdomain.recurly.com/v2/external_payment_phases/tws7x821sv1z\"/>\n <external_id>external-id</external_id>\n <state>paid</state>\n <currency>USD</currency>\n <total>100</total>\n <line_items type=\"array\">\n <external_charge>\n <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n <external_invoice href=\"https://your-subdomain.recurly.com/v2/external_invoices/sd28t3zdm59r\"/>\n <external_product_reference>\n <id>scvf0zhrsjpu</id>\n <reference_code>reference-code</reference_code>\n <external_connection_type>apple_app_store</external_connection_type>\n <created_at type=\"datetime\">2023-02-06T19:56:18Z</created_at>\n <updated_at type=\"datetime\">2023-02-06T19:56:18Z</updated_at>\n </external_product_reference>\n <description></description>\n <unit_amount>50</unit_amount>\n <currency>USD</currency>\n <quantity>1</quantity>\n <created_at>2023-01-13T17:28:02Z</created_at>\n <updated_at>2023-01-13T17:28:02Z</updated_at>\n </external_charge>\n </line_items>\n <purchased_at>2023-01-13T17:28:02Z</purchased_at>\n <created_at>2022-10-10T21:40:57Z</created_at>\n <updated_at>2022-10-10T21:40:57Z</updated_at>\n</external_invoice>"
schema:
$ref: '#/components/schemas/ExternalInvoice'
'404':
description: Incorrect site or external invoice ID.
content:
application/xml:
schema:
$ref: '#/components/schemas/Error'
example: "<error>\n <symbol>not_found</symbol>\n <description lang=\"en-US\">Couldn't find ExternalInvoice with id</description>\n</error>"
default:
description: Unexpected error.
content:
application/xml:
schema:
$ref: '#/components/schemas/Error'
x-codeSamples:
- lang: PHP
source: "<?php\n\ntry {\n $external_invoice = Recurly_ExternalInvoice::get('p7gnbhfxbe8o');\n print \"External Invoice: $external_invoice\\n\";\n} catch (Recurly_NotFoundError $e) {\n print \"External Invoice does not exist\";\n}"
- lang: Ruby
source: external_invoice = Recurly::ExternalInvoice.find('p7gnbhfxbe8o')
- lang: Python
source: external_invoice = ExternalInvoice.get('p7gnbhfxbe8o')
- lang: Dotnet
source: var external_invoice = ExternalInvoices.Get("p7gnbhfxbe8o");
components:
schemas:
ExternalProductReference:
type: object
properties:
id:
type: string
description: System-generated unique identifier for an external product reference.
reference_code:
type: string
description: A code which associates the external product to a corresponding object or resource in an external platform like the Apple App Store or Google Play Store.
external_connection_type:
type: string
description: Source connection platform.
created_at:
type: string
format: date-time
description: When the external product reference was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external product reference was updated in Recurly.
ExternalInvoiceStateEnum:
type: string
enum:
- paid
Email:
type: string
maxLength: 255
example: verena@example.com
xml:
name: email
ExternalCharge:
type: object
description: Charge from an external resource such as Apple App Store or Google Play Store.
properties:
id:
type: string
title: External invoice ID
description: System-generated unique identifier for an external charge ID, e.g. `e28zov4fw0v2`.
object:
type: string
title: Object type
account:
$ref: '#/components/schemas/AccountMini'
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
unit_amount:
type: string
format: decimal
title: Unit Amount
quantity:
type: integer
description:
type: string
external_product_reference:
$ref: '#/components/schemas/ExternalProductReferenceMini'
created_at:
type: string
format: date-time
title: Created at
description: When the external charge was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external charge was updated in Recurly.
LastName:
type: string
title: Last name
example: Example
xml:
name: last_name
Error:
type: object
title: Error
properties:
symbol:
type: string
description:
type: string
xml:
name: error
FirstName:
type: string
title: First name
example: Verena
xml:
name: first_name
AccountWithCodeOnly:
type: object
title: Account
required:
- account_code
properties:
account_code:
$ref: '#/components/schemas/AccountCode'
xml:
name: account
ExternalPaymentPhase:
type: object
properties:
started_at:
type: string
format: date-time
ends_at:
type: string
format: date-time
starting_billing_period_index:
type: integer
title: Starting Billing Period Index
ending_billing_period_index:
type: integer
title: Ending Billing Period Index
offer_type:
type: string
title: Offer Type
description: Type of discount offer given, e.g. "FREE_TRIAL"
offer_name:
type: string
title: Offer Name
description: Name of the discount offer given, e.g. "introductory"
period_count:
type: integer
title: Period Count
description: Number of billing periods
period_length:
type: string
title: Period Length
description: Billing cycle length
amount:
type: string
format: decimal
title: Amount
minimum: 0
description: Allows up to 9 decimal places
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
created_at:
type: string
format: date-time
title: Created at
description: When the external charge was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external charge was updated in Recurly.
ExternalInvoice:
type: object
properties:
id:
type: string
title: External invoice ID
description: System-generated unique identifier for an external invoice ID, e.g. `e28zov4fw0v2`.
object:
type: string
title: Object type
account:
$ref: '#/components/schemas/AccountMini'
external_subscription:
$ref: '#/components/schemas/ExternalSubscription'
external_payment_phase:
$ref: '#/components/schemas/ExternalPaymentPhase'
external_id:
type: string
description: An identifier which associates the external invoice to a corresponding object in an external platform.
state:
$ref: '#/components/schemas/ExternalInvoiceStateEnum'
total:
type: string
format: decimal
title: Total
currency:
type: string
title: Currency
description: 3-letter ISO 4217 currency code.
line_items:
type: array
items:
$ref: '#/components/schemas/ExternalCharge'
purchased_at:
type: string
format: date-time
description: When the invoice was created in the external platform.
created_at:
type: string
format: date-time
description: When the external invoice was created in Recurly.
updated_at:
type: string
format: date-time
title: Updated at
description: When the external invoice was updated in Recurly.
ExternalSubscription:
type: object
properties:
account:
type: string
description: The URL of the account for the specified external subscription.
external_product_reference:
$ref: '#/components/schemas/ExternalProductReference'
external_payment_phases:
type: array
items:
$ref: '#/components/schemas/ExternalPaymentPhase'
uuid:
type: string
description: Universally Unique Identifier created automatically.
last_purchased:
type: string
format: date-time
description: When a new billing event occurred on the external subscription in conjunction with a recent billing period, reactivation or upgrade/downgrade.
auto_renew:
type: boolean
default: false
description: An indication of whether or not the external subscription will auto-renew at the expiration date.
in_grace_period:
type: boolean
title: In grace period
description: An indication of whether or not the external subscription is in a grace period.
default: false
app_identifier:
type: string
description: Identifier of the app that generated the external subscription.
quantity:
type: integer
default: '1'
description: An indication of the quantity of a subscribed item's quantity.
state:
type: string
description: External subscriptions can be active, canceled, expired, or past_due.
default: active
activated_at:
type: string
format: date-time
description: When the external subscription was activated in the external platform.
canceled_at:
type: string
format: date-time
title: Canceled at
description: When the external subscription was canceled in the external platform.
expires_at:
type: string
format: date-time
description: When the external subscription expires in the external platform.
trial_started_at:
type: string
format: date-time
title: Trial started at
description: When the external subscription trial period started in the external platform.
trial_ends_at:
type: string
format: date-time
title: Trial ends at
description: When the external subscription trial period ends in the external platform.
test:
type: boolean
title: Test
description: An indication of whether or not the external subscription was purchased in a sandbox environment.
default: false
imported:
type: boolean
title: Imported
description: An indication of whether or not the external subscription was created by a historical data import.
default: false
created_at:
type: string
format: date-time
description: When the external subscription was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external subscription was updated in Recurly.
AccountCode:
type: string
description: The unique identifier of the account.
example: 1
xml:
name: account_code
ExternalProductReferenceMini:
type: object
title: External Product Reference details
description: External Product Reference details
properties:
id:
type: string
title: External Product ID
description: System-generated unique identifier for an external product ID, e.g. `e28zov4fw0v2`.
object:
type: string
title: object
reference_code:
type: string
title: reference_code
description: A code which associates the external product to a corresponding object or resource in an external platform like the Apple App Store or Google Play Store.
external_connection_type:
type: string
title: external_connection_type
description: Source connection platform.
created_at:
type: string
format: date-time
description: When the external product was created in Recurly.
updated_at:
type: string
format: date-time
description: When the external product was updated in Recurly.
AccountMini:
allOf:
- $ref: '#/components/schemas/AccountWithCodeOnly'
- properties:
first_name:
allOf:
- $ref: '#/components/schemas/FirstName'
- description: The first name of the account.
last_name:
allOf:
- $ref: '#/components/schemas/LastName'
- description: The last name of the account.
email:
allOf:
- $ref: '#/components/schemas/Email'
- description: The email address of the account.
securitySchemes:
api_key:
type: http
description: Enter the API key as the username and set the password to an empty string. You can locate and manage your API keys from the [API Credentials](https://app.recurly.com/go/developer/api_keys) page.
scheme: basic