chore: updates API reference docs

This commit is contained in:
olivermrbl
2020-12-15 13:49:45 +01:00
parent 14585a7b32
commit 34e6c52745
16 changed files with 1149 additions and 423 deletions

View File

@@ -1,11 +1,34 @@
title: Carts
domain: store
routes:
- method: POST
path: /carts
- method: GET
path: /carts/:id
- method: POST
path: /carts/:id
- method: POST
path: /carts/:id/line-items
- method: POST
path: /carts/:id/line-items/:line_id
- method: DELETE
path: /carts/:id/line-items/:line_id
- method: POST
path: /carts/:id/payment-sessions
- method: DELETE
path: /carts/:id/payment-sessions/:provider_id
- method: POST
path: /carts/:id/payment-method
- method: POST
path: /carts/:id/shipping-methods
- method: DELETE
path: /carts/:id/discounts/:code
route: /carts
description: >
A Cart is the preliminary step to an Order. The Cart holds a collection of
items that the customer wishes to purchase, along with the customer's
preferred payment and shipping method.
endpoints:
preferred payment and shipping method.
endpoints:
- path: /
method: POST
title: Create a Cart
@@ -35,7 +58,7 @@ endpoints:
- path: /:id
method: POST
title: Update a Cart
params:
params:
- name: id
type: String
description: Id of the cart.
@@ -68,8 +91,8 @@ endpoints:
calling the endpoint with an array of discounts.
- path: /:id/line-items
method: POST
title: Add a Line Item to a Cart
params:
title: Add line item
params:
- name: id
type: String
body:
@@ -90,7 +113,7 @@ endpoints:
functionality.
- path: /:id/line-items/:line_id
method: POST
title: Update a Line Item
title: Update line item
params:
- name: id
type: String
@@ -108,7 +131,7 @@ endpoints:
the inventory level cannot fulfill the desired quantity.
- path: /:id/line-items/:line_id
method: DELETE
title: Remove a Line Item
title: Remove line item
params:
- name: id
type: String
@@ -120,8 +143,8 @@ endpoints:
Removes a the given line item from the cart.
- path: /:id/discounts/:code
method: DELETE
title: Remove a Discount Code
params:
title: Remove discount code
params:
- name: id
type: String
description: Id of the cart.
@@ -131,8 +154,8 @@ endpoints:
description: Removes a discount code from the cart.
- path: /:id/payment-sessions
method: POST
title: Initialize Payment Sessions for a Cart
params:
title: Create payment sessions
params:
- name: id
type: String
description: Id of the cart.
@@ -141,7 +164,7 @@ endpoints:
the cart. This is usually called when a customer proceeds to checkout.
- path: /:id/payment-sessions/:provider_id
method: DELETE
title: Delete a Payment Session
title: Delete payment session
params:
- name: id
type: String
@@ -156,12 +179,12 @@ endpoints:
reaches a state that cannot be recovered from.
- path: /:id/payment-method
method: POST
title: Set the Payment Method for a Cart
params:
title: Add payment method
params:
- name: id
type: String
description: Id of the cart.
body:
body:
- name: provider_id
type: String
required: true
@@ -182,12 +205,12 @@ endpoints:
payment.
- path: /:id/shipping-methods
method: POST
title: Add a Shipping Method to a Cart
title: Add shipping method
params:
- name: id
type: String
description: Id of the cart.
body:
body:
- name: option_id
type: String
required: true
@@ -199,7 +222,7 @@ endpoints:
fulfillment of the order. Look at the documentation for your installed
fulfillment providers to find out what to send.
description: >
Adds a shipping method to the cart.
Adds a shipping method to the cart.
response: |
{
"cart": {

View File

@@ -1,13 +1,30 @@
title: Customers
domain: store
routes:
- method: POST
path: /customers
- method: GET
path: /customers/:id
- method: POST
path: /customers/:id
- method: POST
path: /customers/:id/addresses
- method: POST
path: /customers/:id/:address_id
- method: POST
path: /customers/:id/payment-methods
- method: POST
path: /customers/:id/reset-password
- method: POST
path: /customers/:id/reset-password-token
route: /customers
description: >
Customers can create a login to view Order history and manage details.
Customers must have unique emails.
endpoints:
endpoints:
- path: /
method: POST
title: Create a Customer Login
title: Create customer
body:
- name: email
type: String
@@ -32,48 +49,10 @@ endpoints:
Creates a customer profile with the given details. If the email has been
used on previous orders the newly created Customer profile will be able to
view the order history associated with this email.
- path: /password-reset
method: POST
title: Reset Customer password
body:
- name: email
type: String
required: true
description: The email of the Customer.
- name: token
type: String
required: true
description: >
The token that will be used to reset the password. Should be generated
with a prior call to `/password-token`.
- name: password
type: String
required: true
description: >
The new password to authenticate the user with.
description: >
Resets a customer's password. The reset call requires a valid token
- path: /password-token
method: POST
title: Request Customer password reset token
body:
- name: email
type: String
required: true
description: The email of the Customer profile to reset password for.
description: >
Generates a reset password token. The token should be sent to the customer
via an email provider. Note that this doesn't send any emails it only
generates the token and informs listeners to
`customer.password_token_generated` that the token was created.
- path: /:id
method: GET
title: Retrieve Customer
params:
title: Retrieve customer
params:
- name: id
type: String
description: The id of the Customer to retrieve.
@@ -83,8 +62,8 @@ endpoints:
- path: /:id
method: POST
title: Update Customer details
params:
title: Update customer
params:
- name: id
type: String
description: The id of the customer.
@@ -105,10 +84,9 @@ endpoints:
description: >
Updates the customer's details. The customer identified by `id` must be
authenticated in order to call this endpoint.
- path: /:id/addresses
method: POST
title: Create a new Customer address
title: Create customer shipping address
params:
- name: id
type: String
@@ -123,7 +101,7 @@ endpoints:
- path: /:id/addresses/:address_id
method: POST
title: Update a Customer address
title: Update customer shipping address
params:
- name: id
type: String
@@ -141,8 +119,8 @@ endpoints:
- path: /:id/payment-methods
method: GET
title: Retrieve Customer's saved payment methods
params:
title: Retrieve saved payment methods
params:
- name: id
type: String
description: The id of the customer.
@@ -151,16 +129,98 @@ endpoints:
will only return in methods in the case where the payment provider allows
payment methods to be saved. The customer must be authenticated in order
to call this endpoint.
- path: /password-reset
method: POST
title: Reset password
body:
- name: email
type: String
required: true
description: The email of the Customer.
- name: token
type: String
required: true
description: >
The token that will be used to reset the password. Should be generated
with a prior call to `/password-token`.
- name: password
type: String
required: true
description: >
The new password to authenticate the user with.
description: >
Resets a customer's password. The reset call requires a valid token
- path: /password-token
method: POST
title: Generate password reset token
body:
- name: email
type: String
required: true
description: The email of the Customer profile to reset password for.
description: >
Generates a reset password token. The token should be sent to the customer
via an email provider. Note that this doesn't send any emails it only
generates the token and informs listeners to
`customer.password_token_generated` that the token was created.
response: |
{
"customer": {
"_id": "5ea80c76d9549d0006c21da7",
"email": "mrs@potato.com",
"orders": [],
"shipping_addresses": [],
"first_name": "Potato",
"last_name": "Head",
"id": "cus_4eThzYSuGv",
"email": "iron@man.com",
"first_name": "Tony",
"last_name": "Stark",
"billing_address": {
"id": "addr_WgNn0BSfIu",
"customer_id": "cus_4eThzYSuGv",
"company": "Stark Industries",
"first_name": "Tony",
"last_name": "Stark",
"address_1": "Hollywood Boulevard 1",
"address_2": null,
"city": "Los Angeles",
"country_code": "US",
"province": "CA",
"postal_code": "90046",
"phone": null,
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"deleted_at": null,
"metadata": null
},
"shipping_addresses": [{
"id": "addr_WgNn0BSfIu",
"customer_id": "cus_4eThzYSuGv",
"company": "Stark Industries",
"first_name": "Tony",
"last_name": "Stark",
"address_1": "Hollywood Boulevard 1",
"address_2": null,
"city": "Los Angeles",
"country_code": "US",
"province": "CA",
"postal_code": "90046",
"phone": null,
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"deleted_at": null,
"metadata": null
}],
"phone": "4242424242",
"has_account": false,
"orders": [{
"id": "order_fi13oadpo2r3vc2g4592",
"status": "pending",
"fulfillment_status": "shipped",
"payment_status": "captured",
"display_id": 50433,
"total": 4004000,
"metadata": null
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": {}
}
}

View File

@@ -1,235 +1,137 @@
title: Orders
domain: store
routes:
- method: POST
path: /orders
- method: GET
path: /orders/:id
route: /orders
description: >
An Order represents a selection of items purchased and holds information about
how the items have been purchased and will be fulfilled.
An order represents a selection of items purchased and holds information about
how the items have been purchased and will be fulfilled.
endpoints:
- path: /:id
method: GET
title: Retrieve an Order
params:
title: Retrieve an order
params:
- name: id
type: String
description: The id of the order.
description: >
Retrieves an order.
Retrieves an order.
- path: /
method: POST
title: Creates an Order
title: Creates an order
body:
- name: cartId
- name: cart_id
type: String
required: true
description: Id of the cart from which the order should be created.
description: >
Creates an order from a cart.
response: |
{
"_id": "5f65c961395b3e0021d8f994",
"status": "pending",
"fulfillment_status": "not_fulfilled",
"payment_status": "awaiting",
"display_id": "1000",
"payment_method": {
"_id": "5f65c961395b3e0021d8f995",
"provider_id": "provider",
"data": {
"id": "importantForPaymentProvider",
"more": "information"
}
},
"discounts": [
{
"regions": [
"5f40ce8f7743b30021337e2b",
"5f4788eff847d30021ac331d",
"5f4cb9a07435de0021c69f09"
"order": {
"id": "order_fi13oadpo2r3vc2g4592",
"status": "pending",
"fulfillment_status": "shipped",
"payment_status": "captured",
"email": "iron@man.com",
"billing_address": {
"id": "addr_WgNn0BSfIu",
"customer_id": "cus_4eThzYSuGv",
"company": "Stark Industries",
"first_name": "Tony",
"last_name": "Stark",
"address_1": "Hollywood Boulevard 1",
"address_2": null,
"city": "Los Angeles",
"country_code": "US",
"province": "CA",
"postal_code": "90046",
"phone": null,
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"deleted_at": null,
"metadata": null
},
"shipping_address": {
"id": "addr_WgNn0BSfIu",
"customer_id": "cus_4eThzYSuGv",
"company": "Stark Industries",
"first_name": "Tony",
"last_name": "Stark",
"address_1": "Hollywood Boulevard 1",
"address_2": null,
"city": "Los Angeles",
"country_code": "US",
"province": "CA",
"postal_code": "90046",
"phone": null,
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"deleted_at": null,
"metadata": null
},
"items": [
{
"id": "item_fn2uaQH95vG9ZMnhj2aU03xg",
"cart_id": null,
"order_id": "order_s9RojwCU2AM8RztcldM2Uof7",
"swap_id": null,
"title": "Ironman suit",
"description": "Awesome Ironman suit",
"thumbnail": null,
"is_giftcard": false,
"should_merge": false,
"allow_discounts": true,
"unit_price": 119600,
"variant_id": "variant_rdEH6PykBuH57giw",
"quantity": 1,
"fulfilled_quantity": 1,
"returned_quantity": 0,
"shipped_quantity": 0,
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
],
"_id": "5f626102bd79500021ea17a3",
"is_giftcard": false,
"usage_count": 6,
"disabled": false,
"code": "TEST",
"discount_rule": {
"valid_for": [],
"_id": "5f626102bd79500021ea17a4",
"description": "TEST",
"value": 99,
"type": "percentage",
"allocation": "total"
}
}
],
"shipping_methods": [
{
"name": "Always Free",
"items": [],
"_id": "5f5b7c1b55c13000213c0989",
"data": {
"id": "manual-fulfillment"
},
"profile_id": "5f3e8fd5cac0ff0021a2be66",
"price": 0,
"provider_id": "manual"
}
],
"items": [
{
"is_giftcard": false,
"has_shipping": true,
"shipped_quantity": 0,
"returned": false,
"fulfilled": false,
"fulfilled_quantity": 0,
"returned_quantity": 0,
"_id": "5f65c927395b3e0021d8f984",
"title": "Item",
"description": "70x140",
"quantity": 1,
"thumbnail": "",
"content": {
"unit_price": 316,
"variant": {
"_id": "5f40f0a2b687940021667170",
"barcode": "",
"image": "",
"published": false,
"inventory_quantity": 20,
"allow_backorder": false,
"manage_inventory": true,
"title": "1234",
"sku": "SKU1234",
"ean": "5713682002297",
"options": [
{
"_id": "5f40f0a2b687940021667171",
"value": "70x140",
"option_id": "5f40f0a2b687940021667163"
}
],
"prices": [
{
"_id": "5f40f0a2b687940021667172",
"currency_code": "EUR",
"amount": 44
},
{
"_id": "5f40f0a2b687940021667173",
"currency_code": "DKK",
"amount": 316
}
],
"__v": 0
},
"product": {
"_id": "5f40f0a2b687940021667162",
"description": "100% Good",
"tags": "",
"is_giftcard": false,
"images": [],
"thumbnail": "",
"variants": [
"5f40f0a2b687940021667164",
"5f40f0a2b687940021667168",
"5f40f0a2b68794002166716c",
"5f40f0a2b687940021667170",
"5f40f0a2b687940021667174"
],
"published": false,
"title": "Item",
"options": [
{
"values": [],
"_id": "5f40f0a2b687940021667163",
"title": "Size"
}
],
"__v": 0
},
"quantity": 1
},
"refundable": 3.95
}
],
"shipping_address": {
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
},
"billing_address": {
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
},
"region_id": "5f40ce8f7743b30021337e2b",
"email": "jojo@jon.com",
"customer_id": "5f42870e715758002170ed86",
"cart_id": "5f4bd6b47435de0021c69f04",
"tax_rate": 0.25,
"currency_code": "DKK",
"shipments": [],
"fulfillments": [],
"returns": [],
"refunds": [],
"created": "2020-09-19T09:03:29.000Z",
"shipping_total": 0,
"discount_total": 312.84,
"tax_total": 0.79,
"subtotal": 316,
"total": 3.95,
"refunded_total": 0,
"refundable_amount": 3.95,
"region": {
"_id": "5f40ce8f7743b30021337e2b",
"tax_rate": 0.25,
"countries": [
"DK"
],
"payment_providers": [
"provider"
],
"fulfillment_providers": [
"manual"
],
"name": "Denmark",
"currency_code": "DKK",
"tax_code": "D25",
"__v": 0
},
"customer": {
"_id": "5f42870e715758002170ed86",
"payment_methods": [],
"has_account": true,
"orders": [
"5f65c961395b3e0021d8f994"
],
"email": "jojo@jon.com",
"shipping_addresses": [
{
"_id": "5f60adf22162dd0021362beb",
"country_code": "DK",
"first_name": "John",
"last_name": "Jones",
"address_1": "Jone ST 9",
"city": "Jonstown",
"postal_code": "12332"
}
],
"__v": 0,
"metadata": {
"stripe_id": "cus_123123123"
},
"first_name": "John",
"last_name": "Jones",
"password_hash": "c2NyeXB0AAEAAAABAAAAAd3Q0jehDc8N3cTdqlPCfeZtF5pILidEESwxcA9Yh8PuojRYBXG0xIiFKVq1xXGfXZlY6zkp1IGBXZDHKb9ZtExImjKlFJNwFxwiiaLFS6oD"
"discounts": [
{
"id": "disc_OpYQN4H8MOWHN2en",
"code": "CCC3C4LL88",
"is_dynamic": true,
"discount_rule_id": "dru_MDyr3lJLa00uxOsY",
"parent_discount_id": "disc_ubtdlkASI7bfUj81",
"metadata": null
}
],
"customer_id": "cus_4eThzYSuGv",
"shipping_methods": [
{
"id": "sm_77bEapbO8tkCqw3yo1NBuCUl",
"shipping_option_id": "so_nRvwHhEdZw",
"order_id": "order_s9RojwCU2AM8RztcldM2Uof7",
"cart_id": null,
"swap_id": null,
"return_id": null,
"price": 0,
"data": {
"id": "Parcel shop",
"city": "Los Angeles",
"postal": "90046"
}
}
],
"metadata": null,
"display_id": 50433,
"currency_code": "dkk",
"region_id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"shipping_total": 0,
"discount_total": 0,
"tax_total": 3850000,
"subtotal": 154000,
"total": 4004000
}
}

View File

@@ -0,0 +1,61 @@
title: Product variants
domain: store
routes:
- method: GET
path: /product-variants
- method: GET
path: /product-variants/:id
route: /product-variants
description: >
A product variant represents a specific type of product. E.g. a variant can differ from other variants based on size and color. A variant will always belong to a product.
endpoints:
- path: /:id
method: GET
title: Retrieve product variant
params:
- name: id
type: String
description: Id of the product variant.
description: >
Retrieves product variant
- path: /
method: GET
title: List product variants
params:
- name: ids
optional: true
type: String
description: String of product variant ids. Id's needs to be separated by comma.
description: >
Retrieves product variants. Specific variants can be retrieved using `ids` query param in the request.
response: |
{
"region": {
"id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"name": "Denmark",
"currency_code": "DKK",
"currency": "DKK",
"tax_rate": 0.25,
"tax_code": null,
"countries": [{
"id": "1001",
"iso_2": "DK",
"iso_3": "DNK",
"num_code": "208",
"name": "denmark",
"display_name": "Denmark"
}],
"payment_providers": [{
"id": "stripe",
"is_installed": true
}],
"fulfillment_providers": [{
"id": "manual",
"is_installed": true
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
}

View File

@@ -0,0 +1,56 @@
title: Products
domain: store
routes:
- method: POST
path: /products
- method: GET
path: /products/:id
route: /products
description: >
A product represents the object, that are to be sold on the website. A product can have variants, that differ by e.g. size and color.
endpoints:
- path: /:id
method: GET
title: Retrieve product
params:
- name: id
type: String
description: Id of the product.
description: >
Retrieves a product
- path: /
method: GET
title: List products
description: >
Retrieves the products for the configured store.
response: |
{
"region": {
"id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"name": "Denmark",
"currency_code": "DKK",
"currency": "DKK",
"tax_rate": 0.25,
"tax_code": null,
"countries": [{
"id": "1001",
"iso_2": "DK",
"iso_3": "DNK",
"num_code": "208",
"name": "denmark",
"display_name": "Denmark"
}],
"payment_providers": [{
"id": "stripe",
"is_installed": true
}],
"fulfillment_providers": [{
"id": "manual",
"is_installed": true
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
}

View File

@@ -1,41 +1,58 @@
title: Regions
domain: store
routes:
- method: POST
path: /regions
- method: GET
path: /regions/:id
route: /regions
description: >
A Region represents a collection of countries that have common pricing
A region represents a collection of countries that have common pricing
schemes, shipping options, tax schemes, etc. Carts must have a region
associated.
endpoints:
- path: /
method: GET
title: List Regions
description: >
Retrieves the regions configured for the store.
- path: /:id
method: GET
title: Retrieve a Region
title: Retrieve region
params:
- name: id
type: String
description: Id of the region.
description: >
Retrieves a region
- path: /
method: GET
title: List regions
description: >
Retrieves the regions configured for the store.
response: |
{
"region": {
"id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"name": "Denmark",
"currency_code": "DKK",
"currency": "DKK",
"tax_rate": 0.25,
"countries": [
"DK"
],
"payment_providers": [
"stripe"
],
"fulfillment_providers": [
"manual"
],
"_id": "5f4cd45b5d1e3200214c0e49"
"tax_code": null,
"countries": [{
"id": "1001",
"iso_2": "DK",
"iso_3": "DNK",
"num_code": "208",
"name": "denmark",
"display_name": "Denmark"
}],
"payment_providers": [{
"id": "stripe",
"is_installed": true
}],
"fulfillment_providers": [{
"id": "manual",
"is_installed": true
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
}

View File

@@ -0,0 +1,53 @@
title: Shipping options
domain: store
routes:
- method: GET
path: /shipping-options
route: /shipping-options
description: >
A shipping option represents a delivery method for products and belongs to a region.
endpoints:
- path: /
method: GET
title: List shipping options
params:
- name: product_ids
optional: true
type: String
description: String of product ids. Id's needs to be separated by comma.
- name: region_id
type: String
description: Id of region
description: >
Retrieves shipping options in a given region. Shipping options for specific products can be retrieved using the `product_ids` query param.
response: |
{
"region": {
"id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"name": "Denmark",
"currency_code": "DKK",
"currency": "DKK",
"tax_rate": 0.25,
"tax_code": null,
"countries": [{
"id": "1001",
"iso_2": "DK",
"iso_3": "DNK",
"num_code": "208",
"name": "denmark",
"display_name": "Denmark"
}],
"payment_providers": [{
"id": "stripe",
"is_installed": true
}],
"fulfillment_providers": [{
"id": "manual",
"is_installed": true
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
}

View File

@@ -0,0 +1,56 @@
title: Swaps
domain: store
routes:
- method: GET
path: /swaps/:cart_id
- method: POST
path: /swaps
route: /swaps
description: >
A swap represents an order, that are created in the process of swapping items in an existing order. In the context of the store, the swap can be retrieved in order to make the payment (if relevant). Furthermore, it is possible to create / complete a swap in the store.
endpoints:
- path: /
method: GET
title: Get swap by cart
params:
- name: cart_id
type: String
description: Id of cart to retrieve swap for.
description: >
Retrieves swap by cart id.
- path: /
method: POST
title: Create swap
description: >
Creates / completes a swap.
response: |
{
"region": {
"id": "reg_HMnixPlOicAs7aBlXuchAGxd",
"name": "Denmark",
"currency_code": "DKK",
"currency": "DKK",
"tax_rate": 0.25,
"tax_code": null,
"countries": [{
"id": "1001",
"iso_2": "DK",
"iso_3": "DNK",
"num_code": "208",
"name": "denmark",
"display_name": "Denmark"
}],
"payment_providers": [{
"id": "stripe",
"is_installed": true
}],
"fulfillment_providers": [{
"id": "manual",
"is_installed": true
}],
"created_at": "2020-12-11T17:03:54.458Z",
"updated_at": "2020-12-11T17:03:54.458Z",
"metadata": null
}
}