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.

Attributes

Attribute	Type	Required	Description
name	string	✓	Name of the shop.
website	string		URL of the website of the shop.
return_address	address		The address a parcel is returned to when delivery fails.
sender_address	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	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:

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

GET /shops

Retrieving a list of shops.

Scope

Any of the following scopes:

organizations.manage
shipments.manage

Request

GET /shops HTTP/1.1
Accept: application/vnd.api+json
Example: https://api.sandbox.myparcel.com/shops

Response

{
  "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"
  }
}

GET /shops/{shop_id}

Retrieve a specific shop.

Scope

Any of the following scopes:

organizations.manage
shipments.manage

Request

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

{
  "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"
    }
  }
}

POST /shops

Create a shop.

Scope

shops.manage

Request

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

{
  "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"
    }
  }
}

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”

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

{
  "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"
    }
  }
}