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.
created_at	integer		Unix timestamp when the shop was created.

Relationship	Type	Required	Description
organization	organizations	✓	The organization the shop belongs to

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://sandbox-api.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"
      },
      "relationships": {
        "organization": {
          "data": {
            "type": "organizations",
            "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
          },
          "links": {
            "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
          }
        }
      },
      "links": {
        "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
      }
    }
  ],
  "meta": {
    "total_pages": 1,
    "total_records": 1
  },
  "links": {
    "self": "https://sandbox-api.myparcel.com/shops?page[number]=1&page[size]=30",
    "first": "https://sandbox-api.myparcel.com/shops?page[number]=1&page[size]=30",
    "last": "https://sandbox-api.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://sandbox-api.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"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.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://sandbox-api.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"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    }
  }
}

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"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.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://sandbox-api.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"
    },
    "relationships": {
      "organization": {
        "data": {
          "type": "organizations",
          "id": "9cdf86e8-333f-4ed9-bb31-4935c780c947"
        },
        "links": {
          "related": "https://sandbox-api.myparcel.com/organizations/9cdf86e8-333f-4ed9-bb31-4935c780c947"
        }
      }
    },
    "links": {
      "self": "https://sandbox-api.myparcel.com/shops/35eddf50-1d84-47a3-8479-6bfda729cd99"
    }
  }
}