# API If you need to add registrations or serial numbers programmatically, you can use the provided API. All endpoints are available at **** ## Generate Access Token To obtain an access token, follow these steps: 1. Navigate to **Shopify Admin**. 2. Go to **Apps**. 3. Select **My Product Registration**. 4. Click on **Settings**. 5. Under the **General** section, find **API Access Token**. 6. Click on **Generate** to create a new access token. Make sure to store the access token securely as it will be used for authenticating API requests. ## Usage ### Authentication Requests to API endpoints require an authentication header with the access token. Set the following in the request header: ``` Authorization: Bearer [access-token] ``` It is preferred to include the access token in the header rather than in the body of the request. ### Registrations - add new (POST) Once the access token is generated, it can be used to register a new product. 1. Make an **HTTP POST request** to the endpoint - . 2. The POST request should have the following **JSON payload**. ``` { "accessToken": "12323213123", "registrations": [ { "productName": "MacBook 2018", "customerEmail": "tom@example.com", "customerName": "Tom Delong", "serialNumbers": [ "123", "321" ], "purchaseDate": "2019-01-01", "greetings": "hello world!", } ] } ``` Or customer data and address can be added in the payload. ``` { "registrations": [ { "productName": "MacBook 2018", "customerEmail": "tom@example.com", "serialNumbers": [ "123", "321" ], "purchaseDate": "2019-01-01", "greetings": "hello world!", "customer": { "id": 123, "firstName": "Testy", "lastName": "Test", "address1": "1 highstreet", "address2": "", "city": "New York", "State": "New York", "country": "US", "postCode": "1234567", "phone": "1234567" } } ] } ``` You can register multiple products in a single call by simply adding additional registration objects to the registrations array. If you need to submit data to a different form (not the default product registration), you'll need to include a new key in the registration: **"type": "form-slug-name".** You can find the form slug name by navigating to **Form > View on the frontend**. For any extra fields, just add them as key-value pairs within the registration object. The key names can be found in the form's design and field options.
### Registrations - Modify existing registration (PUT) Once the access token is generated, it can be used to modify an existing registration, which can be identified by the registration ID found in the admin panel or via the webhook payload. 1. Make a **HTTP PUT request** to the endpoint - 2. The PUT request should have the following **JSON payload** ``` { "accessToken": "12323213123", "registration": { "productName": "MacBook 2018", "customerEmail": "tom@example.com", "customerName": "Tom Delong", "serialNumbers": [ "123", "321" ], "purchaseDate": "2019-01-01", "fields": { "greetings": "hello agaiin", } } } ``` If there are extra fields need to be updated, then put it under **fields** key. ### Update registration status (POST) To update the status of an existing registration, follow these steps: 1. Make an **HTTP POST request** to the endpoint **/api/registrations/:regId/status**. Replace `:regId` with the specific registration ID. 2. The POST request should have the following **JSON payload**: ```json { "accessToken": "12323213123", "status": "new-status", "isPublic": false, "note": "this is a new status", "assets": [ { "name": "receipt", "url": "https://example.com/receipt.jpg" } ] } ``` The `accessToken` field contains your API access token (you can also use the `Authorization: Bearer [access-token]` header as described in the Authentication section). The `status` field should contain the new status value you want to assign to the registration. The `isPublic` field determines whether the status change should be visible to the customer. The `note` field is optional and can contain additional information about the status change. The `assets` field is optional and accepts an array of objects containing `name` and `url` to attach multiple files or images to the status. **Response:** * If the request is successful, the server will return a **200 status code** with the updated registration data. * If an error occurs, the server will respond with an appropriate error message. ### Delete registration (DELETE) To delete a registration, follow these steps: 1. Obtain the registration ID that you want to delete. 2. Make an **HTTP DELETE request** to the endpoint: **/api/registrations/:regId**. Replace `:regId` with the specific registration ID. **Response:** * If the request is successful, the server will return a **200 status code**. * If an error occurs, the server will respond with an appropriate error message. ### Registrations (GET) - Get customer's registrations 1. Make an **HTTP GET request** to the endpoint **/api/registrations** with the email as a query string, e.g., **/api/registrations?email=**. 2. The server will return all registrations associated with the specified email. Available query strings: * **email** - Only get registrations belong to specific email e.g **/api/registrations?email=** * **customerId -** Only get registrations belong to specific customer id (shopify customer id) e.g **/api/registrations?customerId=88888888** * **formSlug** - Only get registration within specific form * **limit** - Limit the results ### Add serial numbers (POST) To add serial numbers, follow these steps: 1. Make an **HTTP POST request** to the endpoint **/api/serial\_numbers**. 2. The POST request should include the following **JSON payload**: ``` { "accessToken": "12323213123", "serialNumbers": [ { "serialNumber": "22018", "sku": "mac123", "customerTags": "VIP,mac", } } ``` The `customerTags` field is a comma-separated list of tags that you want to assign to the customer registering this serial number. ### Get a unused/unregistered serial number (GET) To get a random unregistered serial number, follow these steps: 1. Make an **HTTP GET request** to the endpoint **/api/serial\_number**. 2. If an unregistered serial number is available, the server will return it with a **200 status code**. 3. If no unregistered serial number is found, the server will return a **204 status code**. ### Get serial number information (GET) To retrieve information about a specific serial number, follow these steps: 1. Make an **HTTP GET request** to the endpoint **/api/serial\_numbers/{serialNumber}**, replacing `{serialNumber}` with the actual serial number you want to query. 2. If the serial number exists, the server will return its information with a **200 status code**. 3. If the serial number does not exist, the server will return a **204 status code**. Example request: ``` GET /api/serial_numbers/test123 ``` ### Upload a file/asset/receipt You can upload a file and use the URL as the receipt. The upload process is divided into two parts: 1. Get a presigned URL from the app server. 2. Use the [presigned URL to upload the file directly to Amazon S3](https://docs.aws.amazon.com/AmazonS3/latest/userguide/using-presigned-url.html). Follow these steps: 1. Make an **HTTP GET request** to the endpoint **/api/upload\_file** with the query string parameters `fileName`, `fileType`, and `fileSize`, e.g., **/api/upload\_file?fileName=test.png\&fileType=image/png\&fileSize=123**. 2. The server will return a **signedRequest URL** which you can use to upload the file. The **url** is the final URL of the uploaded file. 3. Make an **HTTP PUT request** to the **signedRequest URL** and include the file in the payload, e.g., ```sh curl -X PUT -T "/path/to/file" "presigned URL" ``` Here are some examples of how to upload the file using JavaScript: ```javascript // Upload the file in Node.js let blobData = new Blob([new Uint8Array(array)], { type: 'image/jpeg' }); const result = await fetch(signedRequestURL, { method: 'PUT', body: blobData }); // Upload the file in the browser // file - is the file object from an HTML input element of type="file" const result = await fetch(signedRequestURL, { method: 'PUT', body: file }); ```