# Shop APIs

Shop related Events and APIs

Last updated: **2024-06-19**
Version: **v0.3.3**
Updated:
- API use default domain and shop token
- Remove tax related fields
- Remove country_code, timezone
- Remove shipping zones province
- Add shipping rate by weight example
- Add updated_at to shop status event / settings
- Update shipping zones example
- Update shop event api url
- Add server url

---

## Events
Push a notification to checkout server when a target event happens.

Testing: https://xshopsit.intercart.app/api/v1/xshop/event
Live: https://xshop.xsfshop.com/api/v1/xshop/event

### E1. Push new shop setup and status changes
When a new shop is setup/inactive/active (re-activate), push a notification to checkout server.

Request:
POST https://{{checkout_host}}/api/v1/xshop/event
Headers: x-checkout-shop-id, x-checkout-api-key
Body:
{
    "shop": {
      "organization_id": "2",
      "organization_name": "Flame",
      "team_id": "tm_00001",
      "team_name": "Team 1",
      "shop_id": "1",
      "shop_name": "shop test 1",
      "default_domain": "shop1.manage.shop",
      "token": "api_token_for_shop", // shop api token
      "status": "new", // "inactive", "active"
      "updated_at": "2024-01-01T00:00:00Z"
    }
}

Response:
200 (OK)

### E2. Push shop setting updates
When a shop setting is updated, push a notification to checkout server.
Push update when primary domain is updated.

Request:
POST https://{{checkout_host}}/api/v1/xshop/event
Headers: x-checkout-shop-id, x-checkout-api-key
Body:
{
    "settings": {
      "id": "1", // shop id
      "name": "Test Store", // shop name
      "email": "[e-mail]", // merchant email
      "domain": "www.testshop.com", // primary domain
      "currency": "USD",
      "weight_unit": "g", // default: g
      "default_domain": "shop1.manage.shop",
      "updated_at": "2024-01-01T00:00:00Z"
    }
}

Response:
200 (OK)

### E3. Push shipping zones updates
When a shop shipping setting is updated, push a notification to checkout server.

Request:
POST https://{{checkout_host}}/api/v1/xshop/event
Headers: x-checkout-shop-id, x-checkout-api-key
Body:
{
    "shipping_zones": [
      {
        "countries": ["US", "UM", ...],
        "price_based_shipping_rates": [
          {
            "id": "93189046361",
            "name": "US Shipping 1",
            "price": "3.01",
            "max_order_subtotal": "0.00", // max = 0.00 (no limit)
            "min_order_subtotal": "0.00"
          },
          {
            "id": "582756728999",
            "name": "US Shipping 2",
            "price": "4.02",
            "max_order_subtotal": "0.00",
            "min_order_subtotal": "70.00"
          }
        ],
        "weight_based_shipping_rates": [
          {
            "id": "637158195367",
            "name": "Shipping by weight 1",
            "price": "2.01",
            "weight_low": "0.00",
            "weight_high": "9.99" // g
          },
          {
            "id": "637158228135",
            "name": "Shipping by weight 2",
            "price": "3.02",
            "weight_low": "10.00", // g
            "weight_high": "0.00" // high = 0.00 (no limit)
          }
        ]
      },
      {
        ...  
      }
    ]
}
Response:
200 (OK)

### E4. Push policies updates
When a policy is updated, push notification to checkout server.

Request:
POST https://{{checkout_host}}/api/v1/xshop/event
Headers: x-checkout-shop-id, x-checkout-api-key
Body:
{
    "policies": [
      {
        "url": "/page/policy/policy_refund_policy",
        "title": "Refund policy",
        "handle": "refund_policy"
      },
      {
        "url": "/page/policy/policy_privacy_policy",
        "title": "Privacy policy",
        "handle": "privacy_policy"
      },
      {
        "url": "/page/policy/policy_terms_of_service",
        "title": "Ters of service",
        "handle": "terms_of_service"
      },
      {
        "url": "/page/policy/policy_shipping_policy",
        "title": "Shipping policy",
        "handle": "shipping_policy"
      },
        {
        "url": "/page/policy/policy_member_policy",
        "title": "Membership Policy",
        "handle": "member_policy"
      }
    
    ]
}

Response:
200 (OK)

## APIs
APIs for checkout server to query about a shop.

### S1. Get shop settings
Get shop settings.

Request:
GET https://{{default_domain}}/api/shop/settings
Header: x-shop-token

Response:
200 (OK)
{
    "settings": {
       "id": "1", // shop id
       "name": "Test Store", // shop name
        ...
    }
}

### S2. Get shipping zones
Get shipping settings.

Request:
GET https://{{default_domain}}/api/shop/shipping_zones
Header: x-shop-token

Response:
200 (OK)
{
    "shipping_zones": [
      {
        "countries": ["US", "UM", ...],
         ...
      },
      ...
    ]
}

### S3. Get policies
Get available policies.

Request:
GET https://{{default_domain}}/api/shop/policies
Header: x-shop-token

Response:
200 (OK)
{
    "policies":
    [
        {
            "url": "/page/policy/policy_refund_policy",
            "title": "Refund policy",
            "handle": "policy_refund_policy"
        },
        ...
    ]
}

---