Moved subscriptions.md up to the root and divided it into concept/eve… (iZettle#139)

Astro-Choco · web-flow · commit 77a672069fe1 · 2021-11-25T08:39:58.000+01:00
* Moved subscriptions.md up to the root and divided it into concept/event-payloads.md and overview.md.
Fixed cross-reference links.

* Changed absolute paths to relevant paths in links.
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@ Currently, Zettle provides APIs for the following markets:
 -   [Product Library](product-library.adoc)
 -   [Inventory](inventory.md)
 -   [Image](image.md)
--   [Pusher](pusher-api/)
+-   [Pusher](pusher-api/overview.md)
 -   [Giftcard](giftcard.md)
 
 All API changes are recorded in [Changelog](CHANGELOG.adoc).
diff --git a/pusher-api/api-reference.md b/pusher-api/api-reference.md
@@ -45,15 +45,15 @@ To create or update a subscription to an event, you will need to be authorized w
 
 E.g. you will require the `READ:PURCHASE` scope if you want to subscribe to the `PurchaseCreated` event. See [the list of scopes for supported events](#supported-events).
 
-For more information on how to get authorization for a particular scope, see [OAuth2 API](https://github.com/iZettle/api-documentation/blob/master/authorization.md).
+For more information on how to get authorization for a particular scope, see [OAuth2 API](../authorization.md).
 
 ## Create a subscription
 
 Creates a webhook subscription to a specific event.
 
 Once the subscription for an event gets created, the Pusher API will publish data on your service whenever that event occurs.
 
-E.g. You created a subscription for the ProductUpdated event. Whenever a product gets updated in the product library, the ProductUpdated event occurs. Then you will receive event data on the destination server that you have exposed publicly. The event data is a payload for the updated product. See the list of [payloads for all events](user-guides/subscriptions.md#payloadAPITable).
+E.g. You created a subscription for the ProductUpdated event. Whenever a product gets updated in the product library, the ProductUpdated event occurs. Then you will receive event data on the destination server that you have exposed publicly. The event data is a payload for the updated product. See the list of [payloads for all events](concept/event-payloads.md#available-event-payloads).
 
 > **Note:** The Pusher API will push data for an event only once. However, there may be cases where it gets published more than once. You don't need to save the data more than once.
 
@@ -71,7 +71,7 @@ See example [Create a webhook subscription](#create-a-webhook-subscription).
 
 |Name |Type |In |Required/Optional |Description
 |---- |---- |---- |---- |----
-|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li>Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](https://github.com/iZettle/api-documentation/blob/master/authorization.md) .</li></ul> 
+|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li>Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](../authorization.md).</li></ul> 
 |uuid |string |query |required | Unique identifier for the subscription as UUID version 1.
 |transportName |string |query |required | The message option used by Pusher API. Currently only `WEBHOOK` is supported. 
 |eventNames |array |query |required | Event names for events that you want to create subscription for. The events are specified in an array. <br/>If you pass an empty array, you will subscribe to all events that the Pusher API supports. In this case, make sure that you have all the corresponding authorization scopes issued. See [the list of scopes](#supported-events).
@@ -127,7 +127,7 @@ See example [Get webhook subscriptions](#get-webhook-subscriptions).
 
 |Name |Type |In |Required/Optional |Description
 |---- |---- |---- |---- |----
-|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](https://github.com/iZettle/api-documentation/blob/master/authorization.md) .</li></ul>  
+|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](../authorization.md).</li></ul>  
 </details>
 
 
@@ -178,7 +178,7 @@ See example [Update a webhook subscription](#update-a-webhook-subscription).
 
 |Name |Type |In |Required/Optional |Description
 |---- |---- |---- |---- |----
-|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](https://github.com/iZettle/api-documentation/blob/master/authorization.md) .</li></ul> 
+|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](../authorization.md).</li></ul> 
 |subscriptionUuid |string |path |required |Unique identifier for an existing subscription as UUID version 1.
 |transportName |string |query |optional | The message option used by the Pusher API. E.g. `WEBHOOK`. You need to specify the same option that you used while creating the subscription.
 |eventNames |array |query |optional | Events that you want to update on the existing subscription. The events are specified in an array.
@@ -225,7 +225,7 @@ See example [Delete a webhook subscription](#delete-a-webhook-subscription).
 
 |Name |Type |In |Required/Optional |Description
 |---- |---- |---- |---- |----
-|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](https://github.com/iZettle/api-documentation/blob/master/authorization.md) .</li></ul> 
+|organizationUuid |string |path |required |Unique identifier for your organization. You can use following options to fill in this value: <br/><ul><li>Use `self` as the value. This will retrieve your organizationUuid from the authentication token in the request.</li><li> Get it by using the `users/me` endpoint of OAuth2 API. For more information, see [OAuth2 API](../authorization.md).</li></ul> 
 |subscriptionUuid |string |path |required |Unique identifier for an existing subscription as UUID version 1.
 </details>
 
@@ -394,7 +394,7 @@ Response
 
 
 ## Related resources
-[Pusher API user guide](user-guides/subscriptions.md)
+[Pusher API user guide](user-guides)
 
 ## Related API reference
 [OAuth2 API Reference](../authorization.md)
diff --git a/pusher-api/concept/event-payloads.md b/pusher-api/concept/event-payloads.md
@@ -1,19 +1,10 @@
-Subscriptions
+Event payloads
 =====================
-With subscriptions, the Pusher API will immediately update you of those events that are triggered on your Zettle Go. So you don't need to pull information from other Zettle Go APIs.
+When an event of your subscription is triggerd, the Pusher API sends `POST` requests with the `payload` field.
 
-* [Understand how events work](#understand-how-events-work)
-    * [Payloads](#payloads)
-* [Plan subscriptions](#plan-subscriptions)
-* [Manage subscriptions](#manage-subscriptions)
-
-## Understand how events work
-The Pusher API provides events for you to listen to certain activities of the Zettle Go app at a working HTTPS endpoint on your server.
-
-After you subscribe to events, when an event is triggered, the Pusher API sends a `POST` request that contains a `payload` field. The field contains event information to the HTTPS endpoint in real time.
-
-### Payloads
-The `payload` field is the response body from other APIs, such as the Inventory API. The Pusher API sends `POST` requests with the `payload` field in the following JSON format:
+The `payload` field is the response body from other APIs, such as the Inventory API. The field contains event information to the HTTPS endpoint in real time.
+ 
+The `payload` field is in the following JSON format:
 
 ```json
 {
@@ -39,8 +30,10 @@ For example, you have a subscription to the `InventoryTrackingStarted` event. Wh
   "timestamp": "2021-04-19T13:17:56.585Z"
 }
 ```
+## Available event payloads
+The following table lists available event payloads.
 
-For more information on event payloads, see the following table.
+> **Note:** As payloads can be updated due to changes of the APIs that provide payloads, you can ignore unknown fields.
 
 <table name="payloadAPITable">
     <thead>
@@ -231,28 +224,3 @@ For more information on event payloads, see the following table.
           </td>
         </tbody>
 </table>
-
-<!-- Ask the team: are the payloads for ApplicationConnectionRemoved, PersonalAssertionDeleted, OrganizationUpdated, and OrganizationFeatureUpdated from the Pusher API? --> 
-> **Note:** As payloads can be updated due to changes of the APIs that provide payloads, you can ignore unknown fields.
-
-
-## Plan subscriptions
-Before subscribing to events, plan which events to use for your use cases.
-
-To get started, you may want to subscribe to the following events:
-
-* To monitor inventory changes in Zettle Point of Sales (POS): `InventoryBalanceChanged`, `InventoryTrackingStarted`, and `InventoryTrackingStopped`
-* To monitor product library changes: `ProductCreated`, `ProductUpdated`, and `ProductDeleted`
-* To monitor purchases: `PurchaseCreated`
-<!-- We can extend this section to be more focused on use cases later on. -->
-
-For more events that you can subscribe, see [Pusher API reference](../api-reference.md).
-
-## Manage subscriptions
-With the Pusher API, you can create, view, update, and delete subscriptions as you need.
-
-* [Create subscriptions](create-subscriptions.md)
-* [View subscriptions](view-subscriptions.md)
-* [Update subscriptions](update-subscriptions.md)
-* [Delete subscriptions](delete-subscriptions.md)
-
diff --git a/pusher-api/overview.md b/pusher-api/overview.md
@@ -0,0 +1,35 @@
+Pusher API overview
+=====================
+With subscriptions, the Pusher API will immediately update you of those events that are triggered on your Zettle Go. So you don't need to pull information from other Zettle Go APIs.
+
+* [Understand how subscriptions work](#understand-how-subscriptions-work)
+* [Plan subscriptions](#plan-subscriptions)
+* [Manage subscriptions](#manage-subscriptions)
+
+## Understand how subscriptions work
+The Pusher API provides events for you to listen to certain activities of the Zettle Go app at a working HTTPS endpoint on your server.
+
+After you subscribe to events, when an event is triggered, the Pusher API sends a `POST` request that contains a `payload` field. The field contains event information to the HTTPS endpoint in real time.
+
+For more information about event payloads, see [event payloads](concept/event-payloads.md).
+
+## Plan subscriptions
+Before subscribing to events, plan which events to use for your use cases.
+
+To get started, you may want to subscribe to the following events:
+
+* To monitor inventory changes in Zettle Point of Sales (POS): `InventoryBalanceChanged`, `InventoryTrackingStarted`, and `InventoryTrackingStopped`
+* To monitor product library changes: `ProductCreated`, `ProductUpdated`, and `ProductDeleted`
+* To monitor purchases: `PurchaseCreated`
+<!-- We can extend this section to be more focused on use cases later on. -->
+
+For more events that you can subscribe, see [Pusher API reference](api-reference.md).
+
+## Manage subscriptions
+With the Pusher API, you can create, view, update, and delete subscriptions as you need.
+
+* [Create subscriptions](user-guides/create-subscriptions.md)
+* [View subscriptions](user-guides/view-subscriptions.md)
+* [Update subscriptions](user-guides/update-subscriptions.md)
+* [Delete subscriptions](user-guides/delete-subscriptions.md)
+
diff --git a/pusher-api/user-guides/create-subscriptions.md b/pusher-api/user-guides/create-subscriptions.md
@@ -12,7 +12,7 @@ Subscribe to events to stay updated of activities that happen on your Zettle Go
 
 ## Prerequisites
 * Make sure that authorization is set up using [Authorization OAuth2 API](../../authorization.md).
-* Make sure that you have set up an HTTPS endpoint as the destination URL on your server for receiving event notifications. The endpoint must be publicly accessible and correctly process event payloads. For events payloads, see [Payloads](subscriptions.md/#payloads).
+* Make sure that you have set up an HTTPS endpoint as the destination URL on your server for receiving event notifications. The endpoint must be publicly accessible and correctly process event payloads. See [event payloads](concept/event-payloads.md).
 * Make sure that you understand the events that are supported by the Pusher API. For events that are supported by the Pusher API, see [Pusher API reference](../api-reference.md#supported-events).
 <!-- to be continued if any -->
 
