Address Management

Overview

Manage shipping addresses for your partner account. Addresses can be set as the account default or assigned to specific asset types to control where purchased items are shipped.

Address CRUD

Create a Saved Address

mutation PartnerCreateSavedAddress($input: PartnerCreateSavedAddressInput!) {
  partnerCreateSavedAddress(input: $input) {
    savedAddress {
      id
      nickname
      name
      street1
      street2
      city
      state
      zip
      country
      phone
      isDefault
      isValidated
    }
    error { message code }
  }
}

Field	Type	Required	Description
nickname	String	Yes	Display name (e.g., "Warehouse", "HQ")
address	ShippingAddressInput	Yes	Full shipping address
isDefault	Boolean	No	Set as account default (default: false, auto-true for first address)

Address Validation

All addresses are verified at creation time. If the address cannot be verified, the request will fail with ADDRESS_VERIFICATION_FAILED and the address will not be saved. Ensure the address is complete and accurate before submitting. If validation continues to fail, contact support.

ShippingAddressInput Fields

Field	Type	Required	Description
name	String	Yes	Recipient name
street1	String	Yes	Street address
street2	String	No	Apartment, suite, unit
city	String	Yes	City
state	String	Yes	State/Province
zip	String	Yes	ZIP/Postal code
country	String	No	Country (default: "US")
phone	String	No	Contact phone number
email	String	No	Contact email

Example

{
  "query": "mutation PartnerCreateSavedAddress($input: PartnerCreateSavedAddressInput!) { partnerCreateSavedAddress(input: $input) { savedAddress { id nickname isDefault isValidated } error { message code } } }",
  "variables": {
    "input": {
      "nickname": "Warehouse",
      "address": {
        "name": "Acme Trading",
        "street1": "123 Main St",
        "city": "Portland",
        "state": "OR",
        "zip": "97201",
        "country": "US"
      }
    }
  }
}

Get a Saved Address

query PartnerGetSavedAddress($input: PartnerGetSavedAddressInput!) {
  partnerGetSavedAddress(input: $input) {
    savedAddress {
      id
      nickname
      name
      street1
      city
      state
      zip
      isDefault
      isValidated
    }
    error { message code }
  }
}

Field	Type	Required	Description
id	ID	One of	Saved address ID
nickname	String	One of	Saved address nickname

Provide either id or nickname, not both.

List Saved Addresses

query PartnerGetSavedAddresses($input: PartnerGetSavedAddressesInput!) {
  partnerGetSavedAddresses(input: $input) {
    savedAddresses {
      id
      nickname
      name
      street1
      city
      state
      zip
      isDefault
    }
    pagination {
      totalCount
      limit
      offset
      hasNextPage
    }
    error { message code }
  }
}

Field	Type	Required	Description
pagination	SimplePaginationInput	No	{ limit, offset } — defaults to limit 20, offset 0

Delete a Saved Address

mutation PartnerDeleteSavedAddress($input: PartnerDeleteSavedAddressInput!) {
  partnerDeleteSavedAddress(input: $input) {
    success
    error { message code }
  }
}

Field	Type	Required	Description
id	ID	Yes	Saved address ID to delete

If the deleted address was the default, the most recently created remaining address is auto-promoted.

Set Default Address

mutation PartnerSetDefaultSavedAddress($input: PartnerSetDefaultSavedAddressInput!) {
  partnerSetDefaultSavedAddress(input: $input) {
    savedAddress {
      id
      nickname
      isDefault
    }
    error { message code }
  }
}

Field	Type	Required	Description
id	ID	Yes	Saved address ID to set as default

The default address is used when no asset-type-specific address is configured.

---

Recipient Address Assignments

Assign a saved address to a specific asset type so purchases of that type ship to that address instead of the account default.

Set Recipient Address

mutation PartnerSetRecipientAddress($input: PartnerSetRecipientAddressInput!) {
  partnerSetRecipientAddress(input: $input) {
    assignment {
      savedAddressId
      savedAddress { id nickname }
      assetType
    }
    error { message code }
  }
}

Field	Type	Required	Description
savedAddressId	ID	No	Address to assign (null to clear)
assetType	String	Yes	Asset type (e.g., SPORTS_CARD, SEALED_TCG, SEALED_WAX) — see Asset Types for eligible values

Set an Asset Type Address

{
  "query": "mutation PartnerSetRecipientAddress($input: PartnerSetRecipientAddressInput!) { partnerSetRecipientAddress(input: $input) { assignment { savedAddressId savedAddress { id nickname } assetType } error { message code } } }",
  "variables": {
    "input": {
      "savedAddressId": "68c1762f-7922-48b2-ac42-244be2c0b43c",
      "assetType": "SPORTS_CARD"
    }
  }
}

Clear an Asset Type Address

Pass savedAddressId: null to remove the assignment and fall back to the account default:

{
  "query": "mutation PartnerSetRecipientAddress($input: PartnerSetRecipientAddressInput!) { partnerSetRecipientAddress(input: $input) { assignment { savedAddressId assetType } error { message code } } }",
  "variables": {
    "input": {
      "savedAddressId": null,
      "assetType": "SPORTS_CARD"
    }
  }
}

Get Recipient Addresses

query PartnerGetRecipientAddresses($input: PartnerGetRecipientAddressesInput!) {
  partnerGetRecipientAddresses(input: $input) {
    assignments {
      savedAddressId
      savedAddress { id nickname name street1 city state zip }
      assetType
    }
    error { message code }
  }
}

Field	Type	Required	Description
assetType	String	No	Filter to a specific asset type

Returns only asset types that have an explicit address assignment. Asset types without an assignment use the account default.

Get All Assignments

{
  "query": "query PartnerGetRecipientAddresses($input: PartnerGetRecipientAddressesInput!) { partnerGetRecipientAddresses(input: $input) { assignments { savedAddressId savedAddress { id nickname } assetType } error { message code } } }",
  "variables": {
    "input": {}
  }
}

Filter by Asset Type

{
  "query": "query PartnerGetRecipientAddresses($input: PartnerGetRecipientAddressesInput!) { partnerGetRecipientAddresses(input: $input) { assignments { savedAddressId savedAddress { id nickname } assetType } error { message code } } }",
  "variables": {
    "input": {
      "assetType": "SEALED_TCG"
    }
  }
}

---

Address Resolution Order

When determining the shipping address for a purchase:

Priority	Scope	Description
Highest	Conditional Bid	recipientAddressId on the conditional bid (see Conditional Bidding)
Medium	Asset Type	Address assigned via partnerSetRecipientAddress
Lowest	Account Default	Address set via partnerSetDefaultSavedAddress

Error Codes

Code	Description
ADDRESS_VERIFICATION_FAILED	Address could not be verified — check fields and retry, or contact support
ADDRESS_NOT_FOUND	Saved address doesn't exist or doesn't belong to your account
INVALID_ASSET_TYPE	Unrecognized asset type string
NOT_FOUND	Saved address ID not found
DUPLICATE_NICKNAME	A saved address with that nickname already exists
VALIDATION_REQUIRED_FOR_DEFAULT	Cannot set an unvalidated address as default