API

If you need to add registrations or serial numbers programmatically, you can use the provided API.

All endpoints are available at https://product-reg.varify.xyz/api/

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 - https://product-reg.varify.xyz/api/registrations.

2. The POST request should have the following JSON payload.

{
    "accessToken": "12323213123",
    "registrations": [
        {
            "productName": "MacBook 2018",
            "customerEmail": "[e-mail]",
            "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": "[e-mail]",
      "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 - https://product-reg.varify.xyz/api/registrations/:regId

2. The PUT request should have the following JSON payload

{
    "accessToken": "12323213123",
    "registration": {
            "productName": "MacBook 2018",
            "customerEmail": "[e-mail]",
            "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.

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=[e-mail].

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=[e-mail]

• 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.

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.,

curl -X PUT -T "/path/to/file" "presigned URL"

Here are some examples of how to upload the file using 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
});