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:
|
| 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"
}
]
}
}