Recurly External Products API

The external-products API from Recurly — 2 operation(s) for external-products.

GitHub OpenAPI

Operations 5

GET /external_products Lists a site's external products #
POST /external_products Creates an External Product #
GET /external_products/{uuid} Fetch an External Product #
PUT /external_products/{uuid} Updates an External Product #
DELETE /external_products/{uuid} Deactivate an External Product #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/recurly:recurly-external-products-api"
All apis
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.

Get an API 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 Specification

recurly-external-products-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Recurly V2 External Products 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-products
  x-displayName: External Products
paths:
  /external_products:
    get:
      summary: Lists a site's external products
      description: 'Returns a list of all your external products from an external resource that are not managed by the Recurly

        platform and instead are managed by third-party platforms like Apple App Store and Google Play Store.'
      tags:
      - external-products
      operationId: listExternalProducts
      responses:
        '200':
          description: ''
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ExternalProduct'
              example: "<external_products type=\"array\">\n  <external_product href=\"https://your-subdomain.recurly.com/v2/external_products/rg6is8p7w4us\">\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/platinum\">\n      <plan_code>platinum</plan_code>\n      <name>Platinum plan</name>\n    </plan>\n    <name>External Product Name</name>\n    <created_at type=\"datetime\">2022-08-25T22:00:32Z</created_at>\n    <updated_at type=\"datetime\">2022-10-10T21:40:50Z</updated_at>\n    <external_product_references type=\"array\">\n      <external_product_reference>\n        <id>rgycreiyhs1q</id>\n        <reference_code>apple-code</reference_code>\n        <external_connection_type>apple_app_store</external_connection_type>\n        <created_at type=\"datetime\">2022-08-29T19:36:39Z</created_at>\n        <updated_at type=\"datetime\">2022-10-10T21:40:50Z</updated_at>\n      </external_product_reference>\n    </external_product_references>\n  </external_product>\n</external_products>"
      x-codeSamples:
      - lang: PHP
        source: "<?php\n\n$external_products = Recurly_ExternalProductList::get();\nforeach ($external_products as $external_product) {\n  print \"External Product: $external_product\\n\";\n}"
      - lang: Ruby
        source: "Recurly::ExternalProduct.find_each do |external_product|\n  puts \"External Product: #{external_product.inspect}\"\nend"
      - lang: Python
        source: "#client version 2.1.6+\nfor external_product in ExternalProduct.all():\n    print 'External Product: %s' % external_product\n"
      - lang: Dotnet
        source: "using System.Linq;\n\nvar externalProducts = ExternalProduct.List();\nwhile (externalProducts.Any())\n{\n\tforeach (var externalProduct in externalProducts)\n\t\tConsole.WriteLine(\"External Product: \" + externalProduct);\n\texternalProducts = externalProducts.Next;\n}"
    post:
      summary: Creates an External Product
      tags:
      - external-products
      operationId: createExternalProducts
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              required:
              - name
              properties:
                name:
                  type: string
                  default: ''
                  description: Name for the External Product
                plan_code:
                  $ref: '#/components/schemas/PlanCode'
                external_product_references:
                  type: array
                  description: List of external product references of the external product.
                  items:
                    $ref: '#/components/schemas/ExternalProductReference'
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "<external_product href=\"https://your-subdomain.recurly.com/v2/external_products/sthyvfittmdb\">\n  <id>su4tr7jvxsxi</id>\n  <plan nil=\"nil\"></plan>\n  <name>newexternalproduct</name>\n  <created_at type=\"datetime\">2023-05-01T16:52:53Z</created_at>\n  <updated_at type=\"datetime\">2023-05-01T16:52:53Z</updated_at>\n  <external_product_references type=\"array\">\n      <external_product_reference>\n          <id>sthyvfjsjak4</id>\n          <reference_code>myrefcode</reference_code>\n          <external_connection_type>google_play_store</external_connection_type>\n          <created_at type=\"datetime\">2023-05-01T16:52:53Z</created_at>\n          <updated_at type=\"datetime\">2023-05-01T16:52:53Z</updated_at>\n      </external_product_reference>\n  </external_product_references>\n</external_product>"
        '404':
          description: Not found
          content:
            application/xml:
              example: "<error>\n    <symbol>not_found</symbol>\n    <description lang=\"en-US\">Couldn't find Plan with merchant_plan_id = fdieie</description>\n</error>"
        '422':
          description: Unprocessable Entity
          content:
            application/xml:
              example: "<errors>\n    <error field=\"external_product.name\" symbol=\"blank\">can't be blank</error>\n</errors>"
      x-codeSamples:
      - lang: xml
        source: "<external_product>\n  <name>newexternalproduct</name>\n  <plan_code>myplancode</plan_code>\n  <external_product_references>\n    <external_product_reference>\n      <reference_code>myrefcode</reference_code>\n      <external_connection_type>google_play_store</external_connection_type>\n    </external_product_reference>\n  </external_product_references>\n</external_product>"
      - lang: PHP
        source: "<?php try {\n  $external_product = new Recurly_ExternalProduct();\n  $external_product->plan_code = 'p1';\n  $external_product->name = 'Cool Plan Name';\n  $external_product_reference = new Recurly_ExternalProductReference();\n  $external_product_reference->reference_code = 'reference_code';\n  $external_product_reference->external_connection_type = 'google_play_store';\n  $external_product->external_product_references = [$external_product_reference];\n  $external_product->create();\n  print \"External Product created: $external_product\\n\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid External Product data: $e\";\n}"
      - lang: Ruby
        source: "external_product_info = (\n  {\n    :name =>          'my-name',\n    :plan_code =>     'my-plan-code',\n    :external_product_references => [Recurly::ExternalProductReference.new(external_connection_type: 'google_play_store', reference_code: 'my-reference-code')]\n  }\n)\nRecurly::ExternalProduct.create!(external_product_info)"
      - lang: Python
        source: "external_product = ExternalProduct(\n  name = 'my-name'\n  plan_code = 'my-plan-code'\n  external_product_references = [\n    recurly.ExternalProductReference(\n      external_connection_type = 'google_play_store',\n      reference_code = 'my-reference-code'\n    )\n  ]\n)\nexternal_product.save()"
      - lang: Dotnet
        source: 'var external_product = new ExternalProduct();

          external_product.Name = "my-name";

          external_product.PlanCode = "google_play_store";

          external_product.ExternalProductReferences.Add(new ExternalProductReference(''google_play_store'', ''my-reference-code''))

          external_product.Create();'
  /external_products/{uuid}:
    get:
      summary: Fetch an External Product
      description: Returns a specific external product.
      tags:
      - external-products
      operationId: fetchExternalProduct
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          default: ''
        required: true
        description: The uuid for the external product.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<external_product href=\"https://your-subdomain.recurly.com/v2/external_products/rg6is8p7w4us\">\n  <plan href=\"https://your-subdomain.recurly.com/v2/plans/platinum\">\n    <plan_code>platinum</plan_code>\n    <name>Platinum plan</name>\n  </plan>\n  <name>External Product Name</name>\n  <created_at type=\"datetime\">2022-08-25T22:00:32Z</created_at>\n  <updated_at type=\"datetime\">2022-10-10T21:40:50Z</updated_at>\n  <external_product_references type=\"array\">\n    <external_product_reference>\n      <id>rgycreiyhs1q</id>\n      <reference_code>apple-code</reference_code>\n      <external_connection_type>apple_app_store</external_connection_type>\n      <created_at type=\"datetime\">2022-08-29T19:36:39Z</created_at>\n      <updated_at type=\"datetime\">2022-10-10T21:40:50Z</updated_at>\n    </external_product_reference>\n  </external_product_references>\n</external_product>"
              schema:
                $ref: '#/components/schemas/ExternalProduct'
        '404':
          description: Incorrect site or external product ID.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              example: "<error>\n  <symbol>not_found</symbol>\n  <description lang=\"en-US\">Couldn't find ExternalProduct 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_product = Recurly_ExternalProduct::get('p7gnbhfxbe8o');\n  print \"External Product: $external_product\\n\";\n} catch (Recurly_NotFoundError $e) {\n  print \"External Product does not exist\";\n}"
      - lang: Ruby
        source: external_product = Recurly::ExternalProduct.find('p7gnbhfxbe8o')
      - lang: Python
        source: external_product = ExternalProduct.get('p7gnbhfxbe8o')
      - lang: Dotnet
        source: var external_product = ExternalProducts.Get("p7gnbhfxbe8o");
    put:
      summary: Updates an External Product
      tags:
      - external-products
      operationId: updateExternalProducts
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          default: ''
        required: true
        description: The uuid for the external product.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              required:
              - plan_code
              properties:
                plan_code:
                  $ref: '#/components/schemas/PlanCode'
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<external_product href=\"https://your-subdomain.recurly.com/v2/external_products/su4tr7jvxsxi\">\n    <id>su4tr7jvxsxi</id>\n    <plan href=\"https://your-subdomain.recurly.com/v2/plans/basicplan5\">\n        <plan_code>basicplan5</plan_code>\n        <name>basicplan5</name>\n    </plan>\n    <name>myname</name>\n    <created_at type=\"datetime\">2023-05-04T21:45:10Z</created_at>\n    <updated_at type=\"datetime\">2023-05-05T23:33:50Z</updated_at>\n    <external_product_references type=\"array\">\n    </external_product_references>\n</external_product>"
        '400':
          description: Bad Request
          content:
            application/xml:
              example: "<error>\n    <symbol>name</symbol>\n    <description>cannot be provided for update</description>\n</error>"
        '404':
          description: Not found
          content:
            application/xml:
              example: "<error>\n    <symbol>not_found</symbol>\n    <description lang=\"en-US\">Couldn't find Plan with merchant_plan_id = fdieie</description>\n</error>"
      x-codeSamples:
      - lang: xml
        source: "<external_product>\n  <plan_code>myplancode</plan_code>\n</external_product>"
      - lang: PHP
        source: "<?php try {\n  $external_product = new Recurly_ExternalProduct();\n  $external_product->uuid = 'swifdu8c9om9';\n  $external_product->plan_code = 'p1';\n  $external_product->update();\n  print \"External Product updated: $external_product\\n\";\n} catch (Recurly_ValidationError $e) {\n  print \"Invalid External Product data: $e\";\n}"
      - lang: Ruby
        source: 'external_product = Recurly::ExternalProduct.find(''su4tr7jvxsxi'')

          external_product.plan_code = ''my-plan-code''

          external_product.save'
      - lang: Python
        source: 'external_product = recurly.ExternalProduct.get(''su4tr7jvxsxi'')

          external_product.plan_code = ''my-plan-code''

          external_product.save()'
      - lang: Dotnet
        source: 'var external_product = ExternalProduct(''su4tr7jvxsxi'')

          external_product.PlanCode= ''my-plan-code''

          external_product.Update()'
    delete:
      summary: Deactivate an External Product
      tags:
      - external-products
      operationId: deactivateExternalProduct
      parameters:
      - in: path
        name: uuid
        schema:
          type: string
          default: ''
        required: true
        description: The uuid for the external product.
      responses:
        '204':
          description: 'Status: 204 No Content'
        '404':
          description: ''
          content:
            application/xml:
              example: "<error>\n  <symbol>not_found</symbol>\n  <description lang=\"en-US\">Couldn't find ExternalProduct with id</description>\n</error>"
      x-codeSamples:
      - lang: PHP
        source: "<?php\ntry {\n  $external_product = new Recurly_ExternalProduct();\n  $external_product->uuid = 'swap0rbgpb1h';\n  $external_product->delete();\n  print \"ExternalProduct $external_product->uuid removed\" . PHP_EOL;\n} catch (Recurly_ValidationError $e) {\n  print \"Validation error: $e\";\n} catch (Recurly_Error $e) {\n  // Could not find external product\n  print \"Bad request: $e\";\n}"
      - lang: Ruby
        source: 'external_product = Recurly::ExternalProduct.find(''p7gnbhfxbe8o'')

          external_product.destroy'
      - lang: Python
        source: 'external_product = ExternalProduct.get(''p7gnbhfxbe8o'')

          external_product.delete()'
      - lang: Dotnet
        source: 'var external_product = ExternalProducts.Get("p7gnbhfxbe8o");

          external_product.Delete();'
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.
    PlanCode:
      type: string
      default: ''
      maxLength: 50
      description: 'Unique code to identify the plan. This code may only contain the following characters: [a-z 0-9 @ - _ .]. Max of 50 characters.'
      example: gold
    Error:
      type: object
      title: Error
      properties:
        symbol:
          type: string
        description:
          type: string
      xml:
        name: error
    ExternalProduct:
      type: object
      properties:
        id:
          type: string
          description: System-generated unique identifier for an external product.
        name:
          type: string
          description: Name to identify the external product in Recurly.
        plan:
          $ref: '#/components/schemas/PlanMini'
        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.
        external_product_references:
          type: array
          description: List of external product references of the external product.
          items:
            $ref: '#/components/schemas/ExternalProductReference'
    PlanMini:
      type: object
      properties:
        plan_code:
          $ref: '#/components/schemas/PlanCode'
        name:
          type: string
          default: ''
          maxLength: 255
          description: Plan name. Max of 255 characters.
          example: Gold Plan
  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