API documentation

API Help

If you have any questions or suggestions related to the API, please do not hesitate to reach out to  support@mothership.fm.

API Features

Mothership provides access to the product feed URLs through the Mothership API.

Product Feeds

A supplier's product feeds are comprised of the Active Products Feed and the Deleted Products Feeds. The Active Products Feed is a list of all of the products and accompanying data. 

In turn, the Deleted Product Feeds are a list of all products that have either been removed from the supplier's store or the retailer no longer has access to. Products listed in the Deleted Products Feeds should be removed from the retailer's store.

Order Placement

Retailers can also use the API to place an order and check on an order's status.

API Version

The Mothership API is currently versioned at V1.0

Accessing the API

Retailers are assigned an Auth Token and a Sandbox Auth Token for each supplier they are connected to. These tokens can be found on the supplier's configuration page in the Mothership Retailer Portal. Should the need arise, you can also generate a new Auth Token on the same page.

HTTPS

All requests to the API must be made over HTTPS. 

Authentication
Requests to the Mothership API require creating an X-Mothership-Auth-Token header and assigning the supplier's auth token to it. 
X-Mothership-Auth-Token: a2fb054b1e51762d52098d28dc98c6469b6d75efc2c8907997b85ae4f523f39c
Sandbox

Mothership can setup a developer sandbox for integrating with the API. For access to the sandbox, please contact support@mothership.fm. Mothership will then invite you to connect to the sandbox supplier store. 

Endpoints

There are 3 endpoints available to retailers.

Get Product Feeds

GET https://api.mothership.fm/v1/products
Example Request
curl -H "X-Mothership-Auth-Token: a2fb054b1e51762d53093d28d698c6469b6d75eec2c8907997b85ae4f624f39c" https://api.mothership.fm/v1/products
Example Response
{
  "active_feed_url": "https://s3-us-west-2.amazonaws.com/kepler.production.feeds/catalogs/1/active_products.json?AWSAccessKeyId=AKIAJ2FIUJQIPLNLYXGQ&Expires=1479781761&Signature=yXOomF2scHBjQVwXH9aHWCk%2F1oU%3D",
  "deleted_feed_urls": [
    "https://s3-us-west-2.amazonaws.com/kepler.production.feeds/catalogs/1/deleted_products.json?AWSAccessKeyId=AKIAJ2FIUJQIPLNLYXGQ&Expires=1479781761&Signature=4T3s9dC5kX2ebUG0R3Jo4e6fb4Y%3D"
  ]
}

Product Feed URLs

Product feed urls are signed such that they are only accessible for a 10 minute window after the API request is made. To access the product feed after the 10 minute window has expired, you must request re-authenticated URLs from the API. 

Product Feed Format

All product feeds are rendered as JSON. You can download a sample feed file here:

Product feeds are comprised of an array of Catalog Products and nested Catalog Variants and Images. A Catalog Product can have 1 or more Catalog Variants and 0 or more Images. A Catalog Variant belongs to Catalog Product and can have 0 or 1 Images. An Image can belong to a Catalog Product or a Catalog Variant.

Properties of Objects in the Product Feeds

Catalog Product
id integer - ID of catalog product
title string - Title of catalog product 
description string - Description of catalog product. May include HTML tags.
product_type string - A categorization of the product.
manufacturer string - The manufacturer or vendor of the Catalog Product
option1 string - The primary differentiator for the catalog product's variants (e.g. Color, Size, Material).
option2 string - The secondary differentiator for the catalog product's variants (e.g. Color, Size, Material).
option3 string - The tertiary differentiator for the catalog product's variants (e.g. Color, Size, Material).
images
array - An array of image objects associated with the catalog product.
variants array - An array of variants associated with the catalog product.
Catalog Variant
id integer - The id of the Catalog Variant.
title string - The title of the catalog Catalog Variant.
barcode string - An identifying number associated with the Catalog Variant, such as a UPC or ISBN.
product_id integer - The ID of the Catalog Product the Catalog Variant belongs to.
grams integer - The weight of the Catalog Variant in grams.
weight integer - The weight of the Catalog Variant in units described by weight_unit.
weight_unit integer - The unit of measurement for weight. 
inventory_policy string - One of the following values:
  • 'continue' - The supplier will accept orders for the item even if the variant's inventory quantity is <= 0.
  • 'deny' - The supplier will not accept orders for a Catalog Variant if the quantity of the order will reduce the variant's inventory quantity to a value <= 0.
  • 'null' - Same as 'deny'
inventory_quantity integer - The quantity of this Catalog Variant that is available to be sold.
position integer - The value used to determine the order of Catalog Variants as they relate to their associated Catalog Product.
price_cents integer - the price of the Catalog Variant in the smallest indivisible currency unit. For example, $1.00 USD would be 100 cents.
price_currency string - The 3 letter ISO 4217 character code for the currency associated with price_cents.
map_cents integer - The Minimum Advertised Price (MAP). This is the lowest price the retailer is allowed to sell the Catalog Variant for.
map_currency string - The 3 letter ISO 4217 character code for the currency associated with map_cents.
requires_shipping boolean - Indicates whether or not the Catalog Variant needs to be shipped in order to be delivered to the customer.
sku string - An alphanumeric code that uniquely identifies the Catalog Variant.
taxable boolean - Indicates that the product is taxed in the Supplier's tax jurisdictions. This may not be applicable to retailers.
option1 string - The value associated with Catalog Product's option1 (e.g. 'Blue' for Color). 
option2 string - The value associated with Catalog Product's option2 (e.g. 'Large' for Size). 
option3 string - The value associated with Catalog Product's option3 (e.g. 'Cotton' for Material).

image image - An image associated with this product. 

Image
id integer - The ID of the Image
src string - The URL from where the image can be downloaded.

Post Create Order

This endpoint lets you create an order in Mothership.

POST https://api.mothership.fm/v1/orders
Request Payload

The request should contain the following arguments: 

  {
    retailer_order_id: '112223333',
    retailer_order_number: '23',
    line_items: [
      {
        retailer_line_item_id: '23423423',
        variant_id: '8',
        quantity: 2
      }
    ],
    shipping_address: {
      address1: '110 W. 112th St.',
      address2: 'Apt. 45',
      city: 'New York',
      company: 'Valence Labs',
      country_code: 'US',
      first_name: 'Gandalf',
      last_name: 'The Grey',
      phone: '3334445555',
      province_code: 'NY',
      zip: '10025'
    }
  }
Request Arguments
retailer_order_id
(REQUIRED) 		String - The id of the order in the retailer's e-commerce system. Must be unique. 
retailer_order_number String - An alternative order identifier, typically supplied to the end-customer.
line_items
(Required) 		Array - A collection of variants and quantities to be purchased from the supplier.
shipping_address
(Required) 		Object - This is the address the order will be shipped to. This is usually retailer's customer's shipping address.
Line Item
retailer_line_item_id
(REQUIRED) 		String - The id of the line item in the retailer's e-commerce system. Must be unique. 
variant_id
(REQUIRED) 		String - The Mothership ID of the item to be purchased. This is available through the product feed.
quantity
(REQUIRED) 		Integer - The quantity of the item associated with variant_id to be purchased. Must be > 0 and <= than the amount available for purchase.
Shipping Address

Since address formats vary significantly throughout the world, not all of the fields below are required. Mothership does not attempt to extrapolate or validate any of the address details you provide. This is where your order is being shipped to, so it is in your interest to provide as much information below as possible. 

address1
(Required) 		String 
address2 String   
city
(Required) 		String
company String  
country_code
(Required) 		String  - 2 character ISO 3166-1 alpha-2 country code.
https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2
first_name
(Required) 		String
last_name String
phone String
province_code
(Strongly Suggested)
 String - 2 character ISO 3166-2 province / subdivision code.
https://en.wikipedia.org/wiki/ISO_3166-2
zip
(Strongly Suggested) 		String 
Error Messages
Example Request
curl -H "Content-Type: application/json" -H "X-Mothership-Auth-Token: a2fb054b1e51762d53093d28d698c6469b6d75eec2c8907997b85ae4f624f39c" -X POST -d '{"retailer_order_id":"333444554","retailer_order_number":"23","line_items":[{"retailer_line_item_id":"23423423","variant_id":"8","quantity":2}],"shipping_address":{"address1":"110 W. 112th St.","address2":"Apt. 45","city":"New York","company":"Valence Labs","country_code":"US","first_name":"Gandalf","last_name":"The Grey","phone":"3334445555","province_code":"NY","zip":"10025"}}' https://api.mothership.fm/v1/orders
Example Response
{
  "order": {
    "id": 3,
    "retailer_id": 1,
    "supplier_id": 1,
    "supplier_order_number": null,
    "supplier_order_id": null,
    "retailer_order_id": "333444554",
    "retailer_order_number": "23",
    "status": "initialized",
    "cancel_reason": null,
    "cancelled_at": null,
    "closed_at": null,
    "subtotal_cents": 18660,
    "subtotal_currency": "CAD",
    "total_cents": 19059,
    "total_currency": "CAD",
    "created_at": "2017-05-01T17:13:13.068Z",
    "updated_at": "2017-05-01T17:13:13.068Z",
    "line_items": [
      {
        "id": 2,
        "order_id": 3,
        "catalog_variant_id": 8,
        "supplier_external_variant_id": "31361741586",
        "sku": "BIND001",
        "title": "Medium / Nurple",
        "options_string": "Medium, Nurple",
        "quantity": 2,
        "unit_price_cents": 9330,
        "unit_price_currency": "CAD",
        "subtotal_cents": 18660,
        "subtotal_currency": "CAD",
        "retailer_external_line_item_id": "23423423",
        "supplier_external_line_item_id": null,
        "total_weight_in_grams": 12700,
        "fulfillment_status": "unfulfilled",
        "fulfillable_quantity": 2,
        "created_at": "2017-05-01T17:13:13.150Z",
        "updated_at": "2017-05-01T17:13:13.150Z"
      }
    ],
    "shipping_address": {
      "id": 2,
      "order_id": 3,
      "address1": "110 W. 112th St.",
      "address2": "Apt. 45",
      "city": "New York",
      "company": "Valence Labs",
      "country_code": "US",
      "first_name": "Gandalf",
      "last_name": "The Grey",
      "phone": "3334445555",
      "province_code": "NY",
      "zip": "10025",
      "created_at": "2017-05-01T17:13:13.173Z",
      "updated_at": "2017-05-01T17:13:13.173Z"
    },
    "shipping_line": {
        "id": 15,
        "order_id": 3,
        "price_cents": 399,
        "price_currency": "CAD",
        "name": "Basic",
        "created_at": "2017-05-01T17:13:13.290Z",
        "updated_at": "2017-05-01T17:13:13.290Z"
      },
    "fulfillments": [],
    "refunds": []
  }
}

Get Order

This endpoint lets you retrieve information about an order previously placed in Mothership.

GET https://api.mothership.fm/v1/orders/:id
Request Arguments
id
(Required) 		The id of the order created in Mothership. This is returned in the create order response
Example Request
curl -H "X-Mothership-Auth-Token: a2fb054b1e51762d53093d28d698c6469b6d75eec2c8907997b85ae4f624f39c" https://api.mothership.fm/v1/orders/3
Example Response
{
  "order": {
    "id": 3,
    "retailer_id": 1,
    "supplier_id": 1,
    "supplier_order_number": "1053",
    "supplier_order_id": "4864044818",
    "retailer_order_id": "333444554",
    "retailer_order_number": "23",
    "status": "completed",
    "cancel_reason": null,
    "cancelled_at": null,
    "closed_at": "2017-05-01T17:46:18.000Z",
    "subtotal_cents": 18660,
    "subtotal_currency": "CAD",
    "total_cents": 4994,
    "total_currency": "CAD",
    "created_at": "2017-05-01T17:13:13.068Z",
    "updated_at": "2017-05-01T17:46:37.998Z",
    "line_items": [
      {
        "id": 2,
        "order_id": 3,
        "catalog_variant_id": 8,
        "supplier_external_variant_id": "31361741586",
        "sku": "BIND001",
        "title": "Medium / Nurple",
        "options_string": "Medium, Nurple",
        "quantity": 2,
        "unit_price_cents": 9330,
        "unit_price_currency": "CAD",
        "subtotal_cents": 18660,
        "subtotal_currency": "CAD",
        "retailer_external_line_item_id": "23423423",
        "supplier_external_line_item_id": null,
        "total_weight_in_grams": 12700,
        "fulfillment_status": "fulfilled",
        "fulfillable_quantity": 0,
        "created_at": "2017-05-01T17:13:13.150Z",
        "updated_at": "2017-05-01T17:46:19.048Z"
      }
    ],
    "shipping_address": {
      "id": 2,
      "order_id": 3,
      "address1": "110 W. 112th St.",
      "address2": "Apt. 45",
      "city": "New York",
      "company": "Valence Labs",
      "country_code": "US",
      "first_name": "Gandalf",
      "last_name": "The Grey",
      "phone": "3334445555",
      "province_code": "NY",
      "zip": "10025",
      "created_at": "2017-05-01T17:13:13.173Z",
      "updated_at": "2017-05-01T17:13:13.173Z"
    },
    "shipping_line": {
        "id": 24,
        "order_id": 3,
        "price_cents": 399,
        "price_currency": "CAD",
        "name": "custom",
        "created_at": "2017-05-01T17:46:37.398Z",
        "updated_at": "2017-05-01T17:46:37.398Z"
      },
    "fulfillments": [
      {
        "id": 4,
        "order_id": 3,
        "supplier_external_id": "4282740434",
        "retailer_external_id": null,
        "carrier": "UPS",
        "tracking_numbers": [
          "1z3234235566346"
        ],
        "tracking_urls": [
          "http://wwwapps.ups.com/etracking/tracking.cgi?InquiryNumber1=1z3234235566346&TypeOfInquiryNumber=T&AcceptUPSLicenseAgreement=yes&submit=Track"
        ],
        "status": "success",
        "notified_retailer": false,
        "created_at": "2017-05-01T17:46:18.380Z",
        "updated_at": "2017-05-01T17:46:18.380Z",
        "fulfillment_line_items": [
          {
            "id": 3,
            "fulfillment_id": 4,
            "purchase_line_item_id": 2,
            "quantity": 2,
            "grams": 6350,
            "created_at": "2017-05-01T17:46:19.129Z",
            "updated_at": "2017-05-01T17:46:19.129Z"
          }
        ]
      }
    ],
    "refunds": [
      {
        "id": 3,
        "order_id": 3,
        "external_id": "211013522",
        "total_amount_cents": 14065,
        "total_amount_currency": "CAD",
        "shipping_amount_cents": 399,
        "shipping_amount_currency": "CAD",
        "refund_method": "discount",
        "created_at": "2017-05-01T17:46:37.497Z",
        "updated_at": "2017-05-01T17:46:37.497Z"
      }
    ]
  }
}

Still need help? Contact Us Contact Us