Shops
=====
A user can have one or more shops and be able to read or manage attached resources like shipments. A shipment is always associated with a shop.
.. seealso::
https://api-specification.myparcel.com/#tag/Shops
Attributes
----------
============== ======================================================== ======== ===========
Attribute Type Required Description
============== ======================================================== ======== ===========
name string ✓ Name of the shop.
website string URL of the website of the shop.
return_address :doc:`address ` The address a parcel is returned to when delivery fails.
sender_address :doc:`address ` The address parcels for this shop are sent from.
reference string A reference for this shop, given by the user.
logo_url string URL of the logo of the shop. Displayed on the branded tracking page.
branding object containing ``returns`` and ``tracking`` style The branding determines the logo URL and colors of the returns portal and branded tracking page.
created_at integer Unix timestamp when the shop was created.
============== ======================================================== ======== ===========
============ =================================================== ======== ===========
Relationship Type Required Description
============ =================================================== ======== ===========
organization :doc:`organizations ` ✓ The organization the shop belongs to
============ =================================================== ======== ===========
Uploading a logo
----------------
When creating or updating a shop resource, it's possible to set a logo for a shop by setting
the ``logo_url`` attribute. If the image is not available on any url, it is possible to upload
a file to the API. The API will then return a ``logo_url`` attribute pointing to the logo.
Uploading a logo is done by specifying the ``logo`` meta property in the POST/PATCH request (see examples below).
The value of this attribute should be an object with two properties:
.. list-table::
:header-rows: 1
:width: 100%
:widths: 20 20 10 50
* - Property
- Type
- Required
- Description
* - mime_type
- string
- ✓
- The mime type of the file. This should be a mime_type of an image.
* - contents
- string
- ✓
- The contents of the file, base64 encoded.
=============
Property
=============
Endpoints
---------
.. raw:: html
GET /shops
Retrieving a list of shops.
**Scope**
Any of the following scopes:
- ``organizations.manage``
- ``shipments.manage``
**Request**
.. code-block:: http
GET /shops HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/shops
**Response**
.. code-block:: json
{
"data": [
{
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
"attributes": {
"name": "MyParcel.com",
"return_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"sender_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"website": "https://www.myparcel.com",
"created_at": 1504801719,
"reference": "MyParcel.com",
"branding": {
"tracking": {
"logo_url": "https://www.mywebsite.com/logo.png"
"primary_color": "#008800",
"secondary_color": "#202025",
"background_color": "#fafafa",
"foreground_color": "#ffffff",
"accent_color": "ffba00",
},
},
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
},
"links": {
"related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
}
],
"meta": {
"total_pages": 1,
"total_records": 1
},
"links": {
"self": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30",
"first": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30",
"last": "https://api.sandbox.myparcel.com/shops?page[number]=1&page[size]=30"
}
}
.. raw:: html
GET /shops/{shop_id}
Retrieve a specific shop.
**Scope**
Any of the following scopes:
- ``organizations.manage``
- ``shipments.manage``
**Request**
.. code-block:: http
GET /shops/{shop_id} HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99
**Response**
.. code-block:: json
{
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
"attributes": {
"name": "MyParcel.com",
"return_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"sender_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"website": "https://www.myparcel.com",
"created_at": 1504801719,
"reference": "MyParcel.com",
"branding": {
"tracking": {
"logo_url": "https://www.mywebsite.com/logo.png"
"primary_color": "#008800",
"secondary_color": "#202025",
"background_color": "#fafafa",
"foreground_color": "#ffffff",
"accent_color": "ffba00",
},
},
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
},
"links": {
"related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
}
}
.. raw:: html
POST /shops
Create a shop.
**Scope**
- ``shops.manage``
**Request**
.. code-block:: http
POST /shops HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/shops
{
"data": {
"type": "shops",
"attributes": {
"name": "MyParcel.com",
"return_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"sender_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"website": "https://www.myparcel.com",
"reference": "MyParcel.com",
"branding": {
"tracking": {
"logo_url": "https://www.mywebsite.com/logo.png"
"primary_color": "#008800",
"secondary_color": "#202025",
"background_color": "#fafafa",
"foreground_color": "#ffffff",
"accent_color": "ffba00",
},
},
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"meta": {
"logo": {
"mime_type": "image/png",
"contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
}
}
}
**Response**
.. code-block:: json
{
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
"attributes": {
"name": "MyParcel.com",
"return_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"sender_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"website": "https://www.myparcel.com",
"created_at": 1504801719,
"reference": "MyParcel.com",
"branding": {
"tracking": {
"logo_url": "https://www.mywebsite.com/logo.png"
"primary_color": "#008800",
"secondary_color": "#202025",
"background_color": "#fafafa",
"foreground_color": "#ffffff",
"accent_color": "ffba00",
},
},
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
},
"links": {
"related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
}
}
.. raw:: html
PATCH /shops/{shop_id}
Update an existing shop.
**Scope**
- ``shops.manage``
**Request**
In this example we're changing the name of the shop to "Sherlock Holmes' trinkets"
.. code-block:: http
PATCH /shops/{shop_id} HTTP/1.1
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99
{
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
"attributes": {
"name": "Sherlock Holmes' trinkets"
}
}
}
**Response**
.. code-block:: json
{
"data": {
"type": "shops",
"id": "35eddf50-1d84-47a3-8479-6bfda729cd99",
"attributes": {
"name": "Sherlock Holmes' trinkets",
"return_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"sender_address": {
"street_1": "Baker Street",
"street_2": "Marylebone",
"street_number": 221,
"street_number_suffix": "B",
"postal_code": "NW1 6XE",
"city": "London",
"country_code": "GB",
"first_name": "Sherlock",
"last_name": "Holmes",
"company": "Holmes Investigations",
"phone_number": "+31 234 567 890"
},
"website": "https://www.myparcel.com",
"created_at": 1504801719,
"reference": "MyParcel.com",
"branding": {
"tracking": {
"logo_url": "https://www.mywebsite.com/logo.png"
"primary_color": "#008800",
"secondary_color": "#202025",
"background_color": "#fafafa",
"foreground_color": "#ffffff",
"accent_color": "ffba00",
},
},
},
"relationships": {
"organization": {
"data": {
"type": "organizations",
"id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
},
"links": {
"related": "https://api.sandbox.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
}
}
},
"meta": {
"logo": {
"mime_type": "image/png",
"contents": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg..."
}
},
"links": {
"self": "https://api.sandbox.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
}
}
}
.. raw:: html