Recurly Shipping Addresses API

The shipping-addresses API from Recurly — 2 operation(s) for shipping-addresses.

GitHub OpenAPI

Operations 4

GET /accounts/{account_code}/shipping_addresses List Account's Shipping Address #
POST /accounts/{account_code}/shipping_addresses Create Shipping Address #
PUT /accounts/{account_code}/shipping_addresses/{shipping_address_id} Update Shipping Address #
DELETE /accounts/{account_code}/shipping_addresses/{shipping_address_id} Delete Shipping Address #

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-shipping-addresses-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-shipping-addresses-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Recurly V2 Shipping Addresses 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: shipping-addresses
  x-displayName: Shipping Addresses
paths:
  /accounts/{account_code}/shipping_addresses:
    get:
      summary: List Account's Shipping Address
      description: Returns a list of shipping addresses for an account.
      tags:
      - shipping-addresses
      operationId: listAccountsShippingAddress
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Unique account identifier.
      - in: query
        name: cursor
        schema:
          type: string
          default: ''
        description: Splits records across pages. Leave blank to return the first page. Follow the URI in the first page's Link header to fetch the next page.
      - in: query
        name: sort
        schema:
          type: string
          default: created_at
        description: 'The attribute that will be used to order records: `created_at`, `updated_at`.'
      - in: query
        name: order
        schema:
          type: string
          default: desc
        description: 'The order in which products will be returned: `asc` for ascending order, `desc` for descending order.'
      - in: query
        name: begin_time
        schema:
          type: string
          format: date-time
          default: ''
        description: Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes greater than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
      - in: query
        name: end_time
        schema:
          type: string
          format: date-time
          default: ''
        description: Operates on the attribute specified by the sort parameter. Filters records to only include those with datetimes less than or equal to the supplied datetime. Accepts an ISO 8601 date or date and time.
      - in: query
        name: per_page
        schema:
          type: integer
          default: '50'
        description: Number of records to return per page, up to a maximum of 200.
      responses:
        '200':
          description: ''
          content:
            application/xml:
              example: "<shipping_addresses type=\"array\">\n  <shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n    <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831/subscriptions\"/>\n    <id type=\"integer\">2438622711411416831</id>\n    <nickname>Work</nickname>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company>Recurly Inc</company>\n    <email>verena@example.com</email>\n    <vat_number nil=\"nil\"/>\n    <address1>123 Main St.</address1>\n    <address2>Suite 101</address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <phone>555-222-1212</phone>\n    <created_at type=\"datetime\">2018-03-19T15:48:00Z</created_at>\n    <updated_at type=\"datetime\">2018-03-19T15:48:00Z</updated_at>\n  </shipping_address>\n  <shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2\">\n    <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\">\n    <shipping_address_id>2</shipping_address_id>\n    <nickname>Home</nickname>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <phone>555-867-5309</phone>\n    <email>verena@example.com</email>\n    <address1>123 Fourth St.</address1>\n    <address2>Apt. 101</address2>\n    <city>San Francisco</city>\n    <state>CA</state>\n    <zip>94105</zip>\n    <country>US</country>\n    <created_at type=\"datetime\">2016-06-14T16:08:42Z</created_at>\n    <updated_at type=\"datetime\">2016-06-14T16:08:42Z</updated_at>\n  </shipping_address>\n</shipping_addresses>"
      x-codeSamples:
      - lang: PHP
        source: "<?php\n\n$shipping_addresses = Recurly_ShippingAddressList::get('x');\n\nforeach ($shipping_addresses as $address) {\n    print(\"Address: $address\\n\");\n}"
      - lang: Ruby
        source: '# First get an account

          account = Recurly::Account.find(''1'')


          # Get all shipping addresses

          shipping_addresses = account.shipping_addresses


          # If you want to pass sorting/filtering params:

          shipping_addresses = account.shipping_addresses.all(sort: :updated_at, order: :asc)'
      - lang: Python
        source: '# first we need any account object

          account = Account.get(''1'')


          # the shipping_addresses method fetches the shipping addresses

          # associated with this account

          shipping_addresses = account.shipping_addresses()'
      - lang: Dotnet
        source: 'var account = Accounts.Get("1");

          var addresses = account.GetShippingAddresses();'
    post:
      summary: Create Shipping Address
      description: 'Creates a new shipping address on an existing account.


        Note: A shipping address can also be created via the Create Account endpoint as well as the Create Subscription endpoint. See the documentation for those endpoints to learn how to create a shipping address during account and subscription creation.'
      tags:
      - shipping-addresses
      operationId: createShippingAddress
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Unique account identifier.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              required:
              - first_name
              - last_name
              - address1
              - city
              - state
              - zip
              - country
              properties:
                nickname:
                  type: string
                  default: ''
                  description: A nickname for the shipping address. Defaults to "first_name last_name". Max of 255 characters.
                first_name:
                  type: string
                  default: ''
                  description: The first name for the account. Max of 255 characters.
                last_name:
                  type: string
                  default: ''
                  description: The last name for the account.  Max of 255 characters.
                company:
                  type: string
                  default: ''
                  description: The company name for the shipping address. Max of 50 characters.
                phone:
                  type: string
                  default: ''
                  description: The phone number for the shipping address.
                email:
                  type: string
                  default: ''
                  description: The email address for the shipping address.
                address1:
                  type: string
                  default: ''
                  description: Address line 1.
                address2:
                  type: string
                  default: ''
                  description: Address line 2.
                city:
                  type: string
                  default: ''
                  description: City
                state:
                  type: string
                  default: ''
                  description: State or region
                zip:
                  type: string
                  default: ''
                  description: Zip or postal code
                country:
                  type: string
                  default: ''
                  description: Country,  [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements).
                vat_number:
                  type: string
                  default: ''
                  description: Customer's VAT number (to avoid having VAT applied, if applicable).
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "<shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831/subscriptions\"/>\n  <id type=\"integer\">2438622711411416831</id>\n  <nickname>Work</nickname>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company>Recurly Inc</company>\n  <email>verena@example.com</email>\n  <vat_number nil=\"nil\"/>\n  <address1>123 Main St.</address1>\n  <address2>Suite 101</address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone>555-222-1212</phone>\n  <created_at type=\"datetime\">2018-03-19T15:48:00Z</created_at>\n  <updated_at type=\"datetime\">2018-03-19T15:48:00Z</updated_at>\n</shipping_address>"
      x-codeSamples:
      - lang: xml
        source: "<!-- Shipping addresses can be created in 3 ways:\n  1. Embed 1 to many shipping address on an account creation\n  2. Embed 1 shipping address on subscription creation\n  3. Create a shipping address on an existing account\nFor 1 and 2, see account and subscription creation respectively\nThis code example shows case #3 -->\n\n<shipping_address>\n  <nickname>Work</nickname>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company>Recurly Inc</company>\n  <phone>555-222-1212</phone>\n  <email>verena@example.com</email>\n  <address1>123 Main St.</address1>\n  <address2>Suite 101</address2>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n</shipping_address>"
      - lang: PHP
        source: '<?php


          // Shipping addresses can be created in 3 ways:

          //   1. Embed 1 to many shipping address on an account creation

          //   2. Embed 1 shipping address on subscription creation

          //   3. Create a shipping address on an existing account

          // For 1 and 2, see account and subscription creation respectively

          // This code example shows case #3


          // First find an existing account

          $account = Recurly_Account::get(''1'');


          // Create your shipping address object

          $shipping_address = new Recurly_ShippingAddress();

          $shipping_address->nickname = "Work";

          $shipping_address->first_name = "Verena";

          $shipping_address->last_name = "Example";

          $shipping_address->company = "Recurly Inc.";

          $shipping_address->phone = "555-555-5555";

          $shipping_address->email = "verena@example.com";

          $shipping_address->address1 = "123 Main St.";

          $shipping_address->city = "San Francisco";

          $shipping_address->state = "CA";

          $shipping_address->zip = "94110";

          $shipping_address->country = "US";


          // Persist the shipping address and link to the account

          $account->createShippingAddress($shipping_address);'
      - lang: Ruby
        source: "# Shipping addresses can be created in 3 ways:\n#   1. Embed 1 to many shipping address on an account creation\n#   2. Embed 1 shipping address on subscription creation\n#   3. Create a shipping address on an existing account\n# For 1 and 2, see account and subscription creation respectively\n# This code example shows case #3\n\n# Fetch an existing account\naccount = Recurly::Account.find('1')\n\n# Call create on the shipping_addresses association\nshipping_address = account.shipping_addresses.create(\n  nickname: \"Work\",\n  first_name: \"Verena\",\n  last_name: \"Example\",\n  company: \"Recurly Inc.\",\n  phone: \"555-555-5555\",\n  email: \"verena@example.com\",\n  address1: \"400 Alabama St.\",\n  city: \"San Francisco\",\n  state: \"CA\",\n  zip: \"94110\",\n  country: \"US\"\n)\n"
      - lang: Python
        source: '# Shipping addresses can be created in 3 ways:

          #   1. Embed 1 to many shipping address on an account creation

          #   2. Embed 1 shipping address on subscription creation

          #   3. Create a shipping address on an existing account

          # For 1 and 2, see account and subscription creation respectively

          # This code example shows case #3


          # First find an existing account

          account = Account.get(''1'')


          # Create your shipping address object

          shad = ShippingAddress()

          shad.nickname = "Work"

          shad.first_name = "Verena"

          shad.last_name = "Example"

          shad.company = "Recurly Inc."

          shad.phone = "555-555-5555"

          shad.email = "verena@example.com"

          shad.address1 = "123 Main St."

          shad.city = "San Francisco"

          shad.state = "CA"

          shad.zip = "94110"

          shad.country = "US"


          # Persist the shipping address and link to the account

          account.create_shipping_address(shad)'
      - lang: Dotnet
        source: '// Shipping addresses can be created in 3 ways:

          //   1. Embed 1 to many shipping address on an account creation

          //   2. Embed 1 shipping address on subscription creation

          //   3. Create a shipping address on an existing account

          // For 1 and 2, see account and subscription creation respectively

          // This code example shows case #3


          // First find an existing account

          var account = Accounts.Get("1");


          // Create your shipping address object

          var newAddress = new ShippingAddress();

          newAddress.FirstName = "Verena";

          newAddress.LastName = "Example";

          newAddress.Email = "verena@example.com";

          newAddress.Address1 = "123 Main St.";

          newAddress.Address2 = "Suite 101";

          newAddress.City = "San Francisco";

          newAddress.State = "CA";

          newAddress.Country = "US";

          newAddress.Zip = "94105";


          // Persist the shipping address and link to the account

          var shippingAddress = account.CreateShippingAddress(newAddress);'
  /accounts/{account_code}/shipping_addresses/{shipping_address_id}:
    put:
      summary: Update Shipping Address
      description: Updates an existing shipping address on an existing account.
      tags:
      - shipping-addresses
      operationId: updateShippingAddress
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Unique account identifier.
      - in: path
        name: shipping_address_id
        schema:
          type: string
          default: ''
        required: true
        description: Shipping address unique identifier.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              type: object
              properties:
                nickname:
                  type: string
                  default: ''
                  description: A nickname for the shipping address. Defaults to "first_name last_name". Max of 255 characters.
                first_name:
                  type: string
                  default: ''
                  description: The first name for the account. Max of 255 characters.
                last_name:
                  type: string
                  default: ''
                  description: The last name for the account.  Max of 255 characters.
                company:
                  type: string
                  default: ''
                  description: The company name for the account. Max of 50 characters.
                phone:
                  type: string
                  default: ''
                  description: The phone number for the shipping address.
                email:
                  type: string
                  default: ''
                  description: The email address for the account.
                address1:
                  type: string
                  default: ''
                  description: Address line 1.
                address2:
                  type: string
                  default: ''
                  description: Address line 2.
                city:
                  type: string
                  default: ''
                  description: City
                state:
                  type: string
                  default: ''
                  description: State or region
                zip:
                  type: string
                  default: ''
                  description: Zip or postal code
                country:
                  type: string
                  default: ''
                  description: Country,  [2-letter ISO code](http://www.iso.org/iso/country_names_and_code_elements).
                vat_number:
                  type: string
                  default: ''
                  description: The VAT number to avoid having the VAT applied (if applicable).
      responses:
        '201':
          description: ''
          content:
            application/xml:
              example: "<shipping_address href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831\">\n  <account href=\"https://your-subdomain.recurly.com/v2/accounts/1\"/>\n  <subscriptions href=\"https://your-subdomain.recurly.com/v2/accounts/1/shipping_addresses/2438622711411416831/subscriptions\"/>\n  <id type=\"integer\">2438622711411416831</id>\n  <nickname>Verena Example</nickname>\n  <first_name>Verena</first_name>\n  <last_name>Example</last_name>\n  <company>Recurly Inc</company>\n  <email>verena@example.com</email>\n  <vat_number nil=\"nil\"/>\n  <address1>123 Main St.</address1>\n  <address2 nil=\"nil\"/>\n  <city>San Francisco</city>\n  <state>CA</state>\n  <zip>94105</zip>\n  <country>US</country>\n  <phone>555-222-1234</phone>\n  <created_at type=\"datetime\">2018-03-19T15:48:00Z</created_at>\n  <updated_at type=\"datetime\">2018-03-19T15:51:15Z</updated_at>\n</shipping_address>"
      x-codeSamples:
      - lang: xml
        source: "<shipping_address>\n  <nickname>newnickname</nickname>\n  <phone>555-222-1234</phone>\n  <address2></address2>\n</shipping_address>"
      - lang: PHP
        source: '<?php


          $shipping_address->nickname = ''newnickname'';

          $shipping_address->phone = ''555-222-1234'';


          $shipping_address->update();'
      - lang: Ruby
        source: "# Call update_attributes on any shipping_address object\nshipping_address.update_attributes(\n  nickname: 'newnickname',\n  phone: '555-222-1234'\n)"
      - lang: Python
        source: '# mutate the properties of any shipping address object

          shipping_address.nickname = ''newnickname''

          shipping_address.phone = ''555-222-1234''


          # then call save

          shipping_address.save()'
      - lang: Dotnet
        source: 'var account = Accounts.Get("1");

          var shippingAddress = account.GetShippingAddresses().First();


          shippingAddress.Nickname = "newnickname";

          shippingAddress.Phone = "555-222-1234";


          var updatedShippingAddress = account.UpdateShippingAddress(shippingAddress);'
    delete:
      summary: Delete Shipping Address
      description: Deletes an existing shipping address from an existing account.
      tags:
      - shipping-addresses
      operationId: deleteShippingAddress
      parameters:
      - in: path
        name: account_code
        schema:
          type: string
          default: ''
        required: true
        description: Unique account identifier.
      - in: path
        name: shipping_address_id
        schema:
          type: string
          default: ''
        required: true
        description: Shipping address unique identifier.
      responses:
        '204':
          description: ''
          content:
            application/xml:
              example: 'Status: 204 No Content'
      x-codeSamples:
      - lang: Ruby
        source: '# call destroy on any shipping address object

          shipping_address.destroy'
      - lang: Python
        source: '# call delete() on any shipping address object

          shipping_address.delete()'
      - lang: Dotnet
        source: 'var account = Accounts.Get("x");

          var shippingAddress = account.GetShippingAddresses().First();


          var id = shippingAddress.Id;

          account.DeleteShippingAddress((long) id);'
components:
  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