API
GuidesWhat’s newGet API token
You’re viewing the reference for API version 2021-01.See the latest version, V2 →
Core Resources

Addresses

Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.
How Addresses relate to other resources
Endpoints

#The address object

Addresses represents one of the many shipping locations a customer may have. Subscriptions are tied to a given address. Each customer can have multiple address objects (many to one aka n:1) in the relationship.

Attributes

  • idinteger
    Unique numeric identifier for the Address.
  • address1string
    The street associated with the Address.
  • address2string
    Any additional information associated with the shipping address.
  • cart_notestringBigCommerceCustomRCS
    The note that that will be passed to the note field of Orders made within the Address.
    cart_note is not currently honored when sent to the Shopify contract api (SCI).
  • citystring
    The city associated with the shipping address.
  • companystring
    The company associated with the shipping address.
  • countrystring
    The country associated with the shipping address.
  • country_codestring
    The 2-letter country code.
  • customer_idinteger
    Unique numeric identifier for the Customer associated with the Address.
  • discount_idinteger
    Unique numeric identifier of Discount that is applied on the Address.
  • first_namestring
    The customer’s first name associated with the address.
  • last_namestring
    The customer’s last name associated with the address.
  • note_attributesarray of objects
    Extra information that is added to the order.
    Show child attributesHide child attributes2
    • namestring
      The name for the note_attribute.
    • valuestring
      The value for the associated note_attribute.
  • phonestring
    The phone number associated with the address.
  • presentment_currencystringSCI
    Presentment currency is the currency used to display prices to the associated on a storefront and at checkout.
    Only set if the currency is different from the store-level currency. Else, will default to store-level currency.
  • provincestring
    The state or province associated with the address.
  • shipping_lines_overridearray of objects
    Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • zipstring
    The zip or postal code associated with the address.
  • cart_attributesarray
    Additional information added to an initial order.
    Important: This field will be deprecated. Please use note_attributes instead.
  • created_atdatetime
    The date and time when the address was created.
  • original_shipping_lines
    Shipping line details.
    Important: This field will be deprecated. Please use shipping_lines_override instead.
  • updated_atdatetime
    The date and time when the Address was last updated.
The address object
{
  "address": {
    "id": 21317826,
    "address1": "1776 Washington Street",
    "address2": "",
    "cart_note": null,
    "city": "Los Angeles",
    "company": "Recharge",
    "country": "United States",
    "country_code": "US",
    "created_at": "2018-11-14T09:00:01",
    "customer_id": 18819267,
    "discount_id": null,
    "first_name": "John",
    "last_name": "Doe",
    "note_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "original_shipping_lines": [
      {
        "code": "Standard Shipping",
        "price": "0.00",
        "title": "Standard Shipping"
      }
    ],
    "phone": "5551234567",
    "presentment_currency": null,
    "province": "California",
    "shipping_lines_override": null,
    "updated_at": "2018-11-14T09:00:01",
    "zip": "90404"
  }
}

#Create an address

POST/customers/{id}/addresses
BigCommerceCustomRCS
Create a new address for a customer.
Scopewrite_customers

Body parameters

  • address1stringRequired
    The street associated with the Address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
  • address2string
    Any additional information associated with the shipping address.
  • cart_notestring
    The note that that will be passed to the note field of Orders made within the Address.
    cart_note is not currently honored when sent to the Shopify contract api (SCI).
  • citystringRequired
    The city associated with the shipping address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
  • companystring
    The company associated with the shipping address.
  • countrystringRequired
    The country associated with the shipping address. Minimal length is 1 character. Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.
  • first_namestringRequired
    The customer’s first name associated with the address. Minimum length is 1 character.
  • last_namestringRequired
    The customer’s last name associated with the address. Minimum length is 1 character.
  • note_attributesarray of objects
    Extra information that is added to the order.
    Show child attributesHide child attributes2
    • namestring
      The name for the note_attribute.
    • valuestring
      The value for the associated note_attribute.
  • phonestringRequired
    The phone number associated with the address. Must be included in the request schema but can be an empty string.
  • presentment_currencystring
    The currency that charges on this address will be processed in. If no presentment_currency is passed, it will be set to your default store currency.
  • provincestringRequired
    The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE. If country is United States then validate with UPS external service.
  • shipping_lines_overridearray of objects
    Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • zipstringRequired
    The zip or postal code associated with the address. Check if the country requires a zip code COUNTRIES_NOT_REQUIRING_ZIP. If not included in the list then a zip code with the minimum length of 1 character is required. If the country is United States then validate against regex UNITED_STATES_ZIP_REGEX and validate with UPS external service. If country is United Kingdom then validate against regex UNITED_KINGDOM_ZIP_REGEX.
  • cart_attributesarray
    Additional information added to an initial order.
    Important note: This field will be deprecated. Please use note_attributes instead.
  • original_shipping_lines
    Shipping line details.
    Important note: This field will be deprecated. Please use shipping_lines_override instead.
POST/customers/{id}/addresses
curl -X POST 'https://api.rechargeapps.com/customers/3411137/addresses' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "address1": "1776 Washington Street",
  "address2": "",
  "city": "Los Angeles",
  "company": "Recharge",
  "country": "United States",
  "first_name": "John",
  "last_name": "Doe",
  "note_attributes": [
    {
      "name": "custom name",
      "value": "custom value"
    }
  ],
  "phone": "5551234567",
  "presentment_currency": "USD",
  "province": "California",
  "shipping_lines_override": [
    {
      "code": "Standard Shipping",
      "price": "0.00",
      "title": "Standard Shipping"
    }
  ],
  "zip": "90404"
}'
Response
{
  "address": {
    "id": 21317826,
    "address1": "1776 Washington Street",
    "address2": "",
    "cart_note": null,
    "city": "Los Angeles",
    "company": "Recharge",
    "country": "United States",
    "country_code": "US",
    "created_at": "2018-11-14T09:00:01",
    "customer_id": 18819267,
    "discount_id": null,
    "first_name": "John",
    "last_name": "Doe",
    "note_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "shipping_lines_override": [
      {
        "code": "Standard Shipping",
        "price": "0.00",
        "title": "Standard Shipping"
      }
    ],
    "phone": "5551234567",
    "presentment_currency": "USD",
    "province": "California",
    "updated_at": "2018-11-14T09:00:01",
    "zip": "90404"
  }
}

#Retrieve an address

GET/addresses/{id}
Retrieves address for customer based on specified address id.
Scoperead_customers
GET/addresses/{id}
curl 'https://api.rechargeapps.com/addresses/21317826' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "address": {
    "id": 21317826,
    "address1": "6419 Ocean Front Walk",
    "address2": "Apt 1",
    "cart_note": null,
    "city": "Los Angeles",
    "company": "",
    "country": "United States",
    "country_code": "US",
    "created_at": "2020-06-16T12:45:35",
    "customer_id": 43845860,
    "discount_id": null,
    "first_name": "Nikola",
    "last_name": "Tesla",
    "note_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "original_shipping_lines": [
      {
        "code": "Standard Shipping",
        "price": "0.00",
        "title": "Standard Shipping"
      }
    ],
    "phone": "1-800-800-8000",
    "presentment_currency": null,
    "province": "California",
    "shipping_lines_override": null,
    "updated_at": "2020-07-10T11:12:58",
    "zip": "90293"
  }
}

#Update an address

PUT/addresses/{id}
Updates an existing address to match the specified parameters.
Scopewrite_customers
When updating the country property you will have to update the zip property as well, otherwise you will receive an error.

Body parameters

  • address1string
    The street associated with the Address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
  • address2string
    Any additional information associated with the shipping address.
  • cart_notestringBigCommerceCustomRCS
    The note that that will be passed to the note field of Orders made within the Address.
    cart_note is not currently honored when sent to the Shopify contract api (SCI).
  • citystring
    The city associated with the shipping address. Minimum length is 1 character. If country is “United States” then validate with UPS external service.
  • companystring
    The company associated with the shipping address.
  • countrystring
    The country associated with the shipping address. Minimal length is 1 character. Check if the store supports shipping to this country. This is set by the merchant in their Shipping Settings page.
  • first_namestring
    The customer’s first name associated with the address. Minimum length is 1 character.
  • last_namestring
    The customer’s last name associated with the address. Minimum length is 1 character.
  • note_attributesarray of objects
    Extra information that is added to the order.
    Show child attributesHide child attributes2
    • namestring
      The name for the note_attribute.
    • valuestring
      The value for the associated note_attribute.
  • phonestring
    The phone number associated with the address. Must be included in the request schema but can be an empty string.
  • provincestring
    The state or province associated with the address. Check if country requires a province COUNTRIES_REQUIRING_PROVINCE. If country is United States then validate with UPS external service.
  • shipping_lines_overridearray of objectsBigCommerceCustomRCSSCI
    Used when shipping rates need to be overridden. If this parameter has value null, rates will be fetched when a related Charge is created or regenerated
    Show child attributesHide child attributes3
    • codestring
      The code of the associated shipping line.
    • pricestring
      The price (in store’s currency) of the associated shipping line.
    • titlestring
      The title of the associated shipping line.
  • zipstring
    The zip or postal code associated with the address. Check if the country requires a zip code COUNTRIES_NOT_REQUIRING_ZIP. If not included in the list then a zip code with the minimum length of 1 character is required. If the country is United States then validate against regex UNITED_STATES_ZIP_REGEX and validate with UPS external service. If country is United Kingdom then validate against regex UNITED_KINGDOM_ZIP_REGEX.
  • cart_attributesarray
    Additional information added to an initial order.
    Important note: This field will be deprecated. Please use note_attributes instead.
  • original_shipping_lines
    Shipping line details.
    Important note: This field will be deprecated. Please use shipping_lines_override instead.
PUT/addresses/{id}
curl -X PUT 'https://api.rechargeapps.com/addresses/21317826' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "address1": "3020 Nebraska Avenue"
}'
Response
{
  "address": {
    "id": 21317826,
    "address1": "3020 Nebraska Avenue",
    "address2": "",
    "cart_note": null,
    "city": "Los Angeles",
    "company": "Recharge",
    "country": "United States",
    "country_code": "US",
    "created_at": "2018-11-14T09:00:01",
    "customer_id": 18819267,
    "discount_id": null,
    "first_name": "John",
    "last_name": "Doe",
    "note_attributes": [
      {
        "name": "custom name",
        "value": "custom value"
      }
    ],
    "original_shipping_lines": [
      {
        "code": "Standard Shipping",
        "price": "0.00",
        "title": "Standard Shipping"
      }
    ],
    "phone": "5551234567",
    "presentment_currency": null,
    "province": "California",
    "shipping_lines_override": null,
    "updated_at": "2018-11-14T09:00:01",
    "zip": "90404"
  }
}

#Delete an address

DELETE/addresses/{id}
It is possible to delete certain addresses from the store using API. However, there are some rules for deleting them. Note: Only Addresses with no active subscriptions can be deleted.
Scopewrite_customers
DELETE/addresses/{id}
curl -X DELETE 'https://api.rechargeapps.com/addresses/21317826' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{}

#List addresses

GET/addresses
Returns all addresses from the store, or addresses for the user given in the parameter.

HTTPS request examples

GET /addresses

GET /customers/:id/addresses
Scoperead_customers
You can combine created_at_min and created_at_max to return all addresses created in the given timespan. This also applies to updated_at_min and updated_at_max parameters

Query parameters

  • created_at_maxstring
    Returns addresses created before the given time.
  • created_at_minstring
    Returns addresses created after the given time.
  • customer_idinteger
    Unique numeric identifier for the customer associated with the address.
  • discount_codestring
    Returns addresses that have the provided discount_code.
  • discount_idstring
    Returns addresses that have the provided discount_id.
  • idsstring
    Filter addresses by id. If passing multiple values, must be comma separated. Non-integer values will result in a 422 error
  • limitstring
    The amount of results. Default is 50 while the maximum is 250.
    Default 50Maximum 250
  • pagestringDeprecated
    The page to show. Default is 1.
    Default 1
    Page-based pagination has been deprecated but still available to use for pages up to a 100. If you need data past this point, use cursor pagination.
  • updated_at_maxstring
    Returns addresses updated before the given date.
  • updated_at_minstring
    Returns addresses updated after the given time.
GET/addresses
curl 'https://api.rechargeapps.com/addresses?limit=3' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "addresses": [
    {
      "id": 48563471,
      "address1": "6419 Ocean Front Walk",
      "address2": "Apt 1",
      "cart_note": null,
      "city": "Los Angeles",
      "company": "",
      "country": "United States",
      "country_code": "US",
      "created_at": "2020-06-16T12:45:35",
      "customer_id": 43845860,
      "discount_id": null,
      "first_name": "Nikola",
      "last_name": "Tesla",
      "note_attributes": [
        {
          "name": "custom name",
          "value": "custom value"
        }
      ],
      "original_shipping_lines": [],
      "phone": "1-800-800-8000",
      "presentment_currency": null,
      "province": "California",
      "shipping_lines_override": null,
      "updated_at": "2020-07-10T11:12:58",
      "zip": "90293"
    }
  ]
}

#Count addresses

GET/addresses/count
Retrieve the count of addresses.

HTTPS request examples

GET /addresses/count

GET /addresses/count?discount_code=10PERCENTOFF

GET /addresses/count?discount_id=123123123

GET /addresses/count?created_at_min=2019-11-11

GET /addresses/count?created_at_max=2019-11-11

GET /addresses/count?updated_at_min=2019-11-11

GET /addresses/count?updated_at_max=2019-11-11

GET /addresses/count?created_at_min=2019-11-10&updated_at_max=2019-11-11
Scoperead_customers
Notes: you can combine multiple parameters with &

Query parameters

  • created_at_maxstring
    Returns addresses created before the given time.
  • created_at_minstring
    Returns addresses created after the given time.
  • discount_codestring
    Returns addresses that have the provided discount_code.
  • discount_idstring
    Returns addresses that have the provided discount_id.
  • updated_at_maxstring
    Returns addresses updated before the given date.
  • updated_at_minstring
    Returns addresses updated after the given time.

Response attributes

GET/addresses/count
curl 'https://api.rechargeapps.com/addresses/count' \
  -H 'X-Recharge-Access-Token: your_api_token'
Response
{
  "count": 6000
}

#Validate an address

POST/addresses/validate
USA only
It is important to validate an address before attempting to create charges for it, as at that point the user may no longer be available to edit incorrect values.
Address validation works only for USA addresses.

Body parameters

  • address1stringRequired
    The street associated with the address.
  • citystringRequired
    The city associated with the address.
  • statestringRequired
    The state associated with the address.
  • zipcodestringRequired
    The zip or postal code associated with the address.

Response attributes

POST/addresses/validate
curl -X POST 'https://api.rechargeapps.com/addresses/validate' \
  -H 'Content-Type: application/json' \
  -H 'X-Recharge-Access-Token: your_api_token' \
  -d '{
  "address1": "1776 Washington Street",
  "city": "santa monica",
  "state": "California",
  "zipcode": "90404"
}'
Response
{
  "city": "santa monica",
  "errors": {},
  "state": "CA",
  "state_name": "California",
  "zipcode": "90404"
}