Create an Ownership

An ownership assigns a Shopify customer, company, or company location to a rep within a team. A resource has at most one owner per team, and each team’s ownerships are independent.

What an ownership controls

Commission. When an order is commissioned, each commission program on the team picks who is paid, in this order:

A commission override on the order’s customer, company, or location.
An ownership of the order’s customer, company, or location in the program’s team.
The territory that contains the order’s shipping postal code.

With an ownership, the program pays the owner and the managers above them in the team hierarchy at each level’s rate, and the resource’s postal code is ignored for that team. A commission override still takes precedence. These commissions report origin: ownership on the commissions endpoint. Account priority. An order can carry a customer, a company, and a location at once. The Account Priorities setting in Velocity ranks them, and the highest-ranked one with an ownership in the team wins. Rep Portal visibility. The owner and the managers above them in the team can see the owned customer, company, or location in the Rep Portal, along with its addresses and orders. Reps with permission to view all accounts see it regardless. Requires a commission program. A team with no commission program has nothing to pay, so its ownerships have no effect on commission or visibility until a program is added. Deleting an ownership returns the resource to territory matching for that team and removes the visibility it granted. Velocity can also create ownerships itself when the Automatic Ownership setting is on: reps then own the customers, companies, and locations they onboard in the Rep Portal.

Creating an ownership

Creating one takes three IDs:

ID	Where it comes from
`alignment_id`	The team. List teams.
`rep_link_id`	The rep’s position in that team. Retrieve the team hierarchy.
`customer_id`, `company_id`, or `location_id`	The numeric Shopify ID of the resource, from the Shopify Admin API.

Find the team

Search teams by name and note the id. rep_levels is ordered from the top of the hierarchy down; the last entry is the lowest level, and only rep links on that level can own resources.

Request

curl "https://api.velocity.shop/alignments/?search=West" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

[
    {
        "id": "2f1b6c1e-8b0a-4f6e-9c3d-1a2b3c4d5e6f",
        "name": "West Coast",
        "rep_levels": [
            {
                "id": "a9d2c7b4-1e3f-4a5b-8c6d-7e8f9a0b1c2d",
                "name": "Manager"
            },
            {
                "id": "5c4d3e2f-1a0b-4c9d-8e7f-6a5b4c3d2e1f",
                "name": "Rep"
            }
        ]
    }
]

Find the rep

Skip this step if you already know which rep should own the resource. Otherwise search reps and note the id. alignments lists the teams the rep belongs to.

Request

curl "https://api.velocity.shop/reps/?search=jane" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

[
    {
        "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
        "identifier": "WC-1",
        "name": "Jane Park",
        "email": "jane@example.com",
        "alignments": [
            {
                "id": "2f1b6c1e-8b0a-4f6e-9c3d-1a2b3c4d5e6f",
                "name": "West Coast"
            }
        ]
    }
]

Find the rep link

Retrieve the team hierarchy. It is a tree of rep links, each with a rep and children. Walk the tree to the link whose rep.id matches your rep and whose rep_level_id is the team’s lowest level. Its id is the rep_link_id.A rep link is not a rep. The same rep has a different link in every team they belong to.

Request

curl "https://api.velocity.shop/alignments/2f1b6c1e-8b0a-4f6e-9c3d-1a2b3c4d5e6f/hierarchy/" \
-H "Authorization: Bearer YOUR_TOKEN"

Response

[
    {
        "id": "0e1f2a3b-4c5d-4e6f-8a9b-0c1d2e3f4a5b",
        "rep_level_id": "a9d2c7b4-1e3f-4a5b-8c6d-7e8f9a0b1c2d",
        "rep": {
            "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
            "identifier": "WC-M",
            "name": "Morgan Lee"
        },
        "children": [
            {
                "id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
                "rep_level_id": "5c4d3e2f-1a0b-4c9d-8e7f-6a5b4c3d2e1f",
                "rep": {
                    "id": "c3d4e5f6-a7b8-4c9d-8e0f-1a2b3c4d5e6f",
                    "identifier": "WC-1",
                    "name": "Jane Park"
            },
                "children": []
            }
        ]
    }
]

Here Jane’s rep link is 7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c.

Create the ownership

Send the team, the rep link, and exactly one of customer_id, company_id, or location_id. Use the numeric part of the Shopify GID: gid://shopify/Customer/6417313005602 is 6417313005602.

Request

curl -X POST "https://api.velocity.shop/ownerships/" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alignment_id": "2f1b6c1e-8b0a-4f6e-9c3d-1a2b3c4d5e6f",
    "rep_link_id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "customer_id": 6417313005602
  }'

Response

{
    "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a",
    "alignment_id": "2f1b6c1e-8b0a-4f6e-9c3d-1a2b3c4d5e6f",
    "rep_link_id": "7f8a9b0c-1d2e-4f3a-8b4c-5d6e7f8a9b0c",
    "customer_id": 6417313005602,
    "company_id": null,
    "location_id": null
}

Changing or removing an owner

A resource has one owner per team, so creating a second ownership for the same resource and team returns 400. To reassign, list the ownerships for the resource, delete the existing one, then create the new one.

List

curl "https://api.velocity.shop/ownerships/?customer_ids=6417313005602" \
  -H "Authorization: Bearer YOUR_TOKEN"

Delete

curl -X DELETE "https://api.velocity.shop/ownerships/d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f7a/" \
  -H "Authorization: Bearer YOUR_TOKEN"

Common errors

Response	Cause
`Must be on the lowest level of the alignment.`	Use a rep link on the team’s lowest level.
`This rep does not belong to the selected alignment.`	The rep link belongs to a different team.
`Invalid ownerships target id.`	Wrong ID, or Velocity has not synced it from Shopify yet.
`A ownership can target exactly one 'customer_id', 'company_id', or 'location_id'.`	Zero or several target IDs were sent.

Home

Guides

API Reference

What an ownership controls

Creating an ownership

Changing or removing an owner

Common errors

​What an ownership controls

​Creating an ownership

​Changing or removing an owner

​Common errors

What an ownership controls

Creating an ownership

Changing or removing an owner

Common errors