Marketplace API reference

The Marketplace API enables all the core interactions that the end users of the marketplace participate in. These include signing up as a new user, managing listings, engaging in transactions, messaging, etc. The Marketplace API is best suited for building the user-facing marketplace UI applications, like the marketplace's web site or mobile apps.

Authentication

Example request:

$ curl -X GET 'https://flex-api.sharetribe.com/v1/api/marketplace/show' \
    -H 'Authorization: bearer ACCESS_TOKEN'

Every call to the Marketplace API must be made with a valid access token included in the API request. The access token must be provided via Authorization HTTP header in each API request in the form of:

Authorization: bearer ACCESS_TOKEN

API clients can obtain access tokens directly via the Authentication API or use the Sharetribe SDK, which provides convenience methods of handling authentication and tokens. Using the SDK is recommended over direct API access.

Some Marketplace API endpoints can be called with both anonymous and user access tokens and some require authenticated user access token. Unless otherwise stated in the documentation of the API endpoint, the endpoint can be called with any valid access token. For details about the access tokens, see the Authentication API reference.

Sharetribe SDK

const sharetribeSdk = require('sharetribe-flex-sdk');

const sdk = sharetribeSdk.createInstance({
  clientId: '<Your Client ID here>'
  baseUrl: '<Base URL here>',
});

Sharetribe SDK is at the moment available for JavaScript.

The Sharetribe SDK makes it easier to authenticate to the Sharetribe Marketplace API. See the JavaScript SDK documentation for more details.

Logging in

sdk.login({
  username: "user@example.com",
  password: "secret-password"
}).then(loginRes => {
  console.log("Login successful.")
});

The SDK automatically maintains user session and manages access tokens after a successful login.

Logging out

sdk.logout().then(loginRes => {
  console.log("Logout successful.")
});

Logging out clears the user session - revokes the refresh token and removes any stored access and refresh tokens.

Rate limits

The following table lists the Marketplace API request rate limits.

Note that the limits apply to specific marketplace environments.

Marketplace environment(s)	Endpoint(s)	Limit	Scope
dev and test (*)	All query endpoints (GET) (**)	Rate limit at 1 request per second (60 requests per minute) on average	Per client IP address
dev and test (*)	All command endpoints (POST) (**)	Rate limit at 1 request per 2 seconds (30 requests per minute) on average	Per client IP address

(*) For marketplace environments created before 2023-01-31, these rate limits will come into effect on 2023-02-15 at 10:00:00 UTC.

(**) The limit applies globally across all API endpoints, so that all requests in total across all endpoints are subject to the limit.

The rate limiters use a token bucket algorithm and allow for a burst of requests. The rate limiters begin to enforce the stated average rate if the burst capacity is exhausted. The burst capacity accumulates back when the request rate remains below the limit.

API requests that are rejected due to a request rate limit receive a response with HTTP status code 429.

For description of the different marketplace environments see here.

See this article for advice on how to handle these limits gracefully.

Marketplace

API prefix

/v1/api/marketplace/

Example resource

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

The marketplace API resource represents the public data about the marketplace.

`marketplace` resource format

Attribute	Description
name	(string) The marketplace name.
description	(string) DEPRECATED: Not in use anymore. New marketplaces will always have `null` value. The marketplace description.

Show marketplace

HTTP request

GET /v1/api/marketplace/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/marketplace/show' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.marketplace.show().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
    "type": "marketplace",
    "attributes": {
      "name": "My Marketplace",
      "description": "My marketplace"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "16c6a4b8-88ee-429b-835a-6725206cd08c"},
    type: "marketplace",
    attributes: {
      name: "My Marketplace",
      description: "My marketplace"
    }
  }
}

Get the marketplace details.

Users

API prefix

/v1/api/users/

Example resource

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "profile": {
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "metadata": {
          "verified": true
        }
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      profile: {
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        metadata: {
          verified: true
        }
      }
    }
  }
}

The user API resource represents public data about marketplace users. See also Current user.

`user` resource format

Attribute	Description
banned	(boolean) DEPRECATED: Flag indicating whether the user is banned. Banned users have all other attributes, except `state`, set to `null` or `false`.
deleted	(boolean) Flag indicating whether the user is deleted. Deleted users have all other attributes set to `null` or `false`.
state	(string) User's state. See `user` states.
createdAt	(string, timestamp) The date and time the user signed up in ISO 8601 format.
profile.displayName	(string) User's chosen display name. Defaults to first name plus initial of last name.
profile.abbreviatedName	(string) Initials of user's first and last names.
profile.bio	(string, nullable) User's bio.
profile.publicData	(object) User's public data. See Extended data for details.
profile.metadata	(object) User's public metadata. See Extended data for details.

`user` states

A user resource type may be in one of the following states:

State	Description
active	The user is active. The user can perform any action that is not restricted because of permissions or by other mechanism.
pendingApproval	The user is pending operator approval. The user won't be able to publish listings or initiate transactions until they're approved by an operator.
banned	The user is banned from the marketplace. The user doesn't have authenticated access to any of the marketplace API endpoints. Users in banned state have all other attributes, except the `banned` flag, set to `null` or `false`.

`user` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
profileImage	image	one	(optional) User's profile image, if any.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show user

HTTP request

GET /v1/api/users/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/users/show?id=3c073fae-6172-4e75-8b92-f560d58cd47c' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var userId = new UUID("3c073fae-6172-4e75-8b92-f560d58cd47c");
sdk.users.show({id: userId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "user",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "profile": {
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "metadata": {
          "verified": true
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "user",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      profile: {
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        metadata: {
          verified: true
        }
      }
    }
  }
}

Get the public details of a single user. You need to know the user's ID.

Query parameters

Parameter	Description
id	(uuid) The id of the user.

Current user

API prefix

/v1/api/current_user/

Example resource

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": true,
      "stripePayoutsEnabled": true,
      "stripeChargesEnabled": true,
      "identityProviders": [
        {
          "idpId": "facebook",
          "userId": "11223344"
        }
      ],
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/allow",
        "read": "permission/allow"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: true,
      stripePayoutsEnabled: true,
      stripeChargesEnabled: true,
      identityProviders: [
        {
          idpId: "facebook",
          userId: "11223344"
        }
      ],
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/allow",
        read: "permission/allow"
      }
    }
  }
}

The currentUser API resource type represents details about the currently authenticated user (i.e. the user to whom the access token, which is used to call the API, belongs).

Most current_user/ API endpoints require an authenticated user access token.

`currentUser` resource format

Attribute	Description
banned	(boolean) DEPRECATED: Flag indicating whether the user is banned. Banned users have all other attributes, except `state`, set to `null` or `false`.
deleted	(boolean) Flag indicating whether the user is deleted. Deleted users have all other attributes set to `null` or `false`.
state	(string) User's state. See `currentUser` states.
createdAt	(string, timestamp) The date and time the user signed up in ISO 8601 format.
email	(string, case insensitive) The user's email address. The email address acts as username.
emailVerified	(boolean) Flag indicating if the user's email address had been verified.
pendingEmail	(string, nullable) If present, the user is in the process of changing their email and have not yet verified the new (pending) address.
stripeConnected	(boolean) Flag indicating if the user has completed creating a Stripe account.
stripePayoutsEnabled	(boolean) DEPRECATED: this flag will always be `false` for Stripe Accounts created via `/stripe_account/create` endpoint and has no effect on how Sharetribe behaves. Flag indicating if the user can accept payouts.
stripeChargesEnabled	(boolean) DEPRECATED: this flag will always be `false` for Stripe Accounts created via `/stripe_account/create` endpoint and has no effect on how Sharetribe behaves. Flag indicating if charges can be created on behalf of the user.
identityProviders	(array) Identity provider accounts this user is associated with. No sort order is guaranteed. See `currentUser` identity provider.
profile.firstName	(string) User's first name.
profile.lastName	(string) User's last name.
profile.displayName	(string) User's chosen display name. Defaults to first name plus initial of last name.
profile.abbreviatedName	(string) Initials of user's first and last names.
profile.bio	(string, nullable) User's bio.
profile.publicData	(object) User's public data. See Extended data for details.
profile.protectedData	(object) User's protected data. See Extended data for details.
profile.privateData	(object) User's private data. See Extended data for details.
profile.metadata	(object) User's public metadata. See Extended data for details.
permissions	(object) User's permissions. See permissionSet for details. This attribute reflects the user's provisional permissions, which may be modified by other factors such as global settings. The user's effective permissions can be fetched via the `effectivePermissionSet` relationship.

`currentUser` identity provider

Describes an identity provider user account that is associated with the current user.

Attribute	Description
idpId	(string) IdP ID of the identity provider.
userId	(string) User's account ID in the identity provider.

`currentUser` states

A currentUser resource type may be in one of the following states:

State	Description
active	The user is active. The user can perform any action that is not restricted because of permissions or by other mechanism.
pendingApproval	The user is pending operator approval. The user won't be able to publish listings or initiate transactions until they're approved by an operator.
banned	The user is banned from the marketplace. The user doesn't have authenticated access to any of the marketplace API endpoints. Users in banned state have all other attributes, except the `banned` flag, set to `null` or `false`.

`currentUser` permissionSet

Object containing the permissions for the current user. For each permission the possible values are "permission/allow" and "permission/deny".

The permission set can have different values when fetched via the permissions attribute and the effectivePermissionSet relationship. The permissions attribute reflects the user's provisional permissions, which may be modified by other factors such as global settings. The user's final permissions, determined after considering all factors, can be obtained via the effectivePermissionSet relationship.

Attribute	Description
postListings	User's permission to post listings. If the permission is denied for the user, the endpoints `POST /own_listings/create_draft`, `POST /own_listings/publish_draft`, `POST /own_listings/create` and `POST /own_listings/open` respond with `403`.
initiateTransactions	User's permission to initiate transactions. If the permission is denied for the user, the endpoint `POST /transactions/initiate` responds with `403`.
read	User's permission to view listings and related data. If the permission is denied for the user, the endpoints `GET /listings/query`, `GET /listings/show`, `GET /users/show`, `GET /timeslots/query`, `GET /reviews/query` and `GET /reviews/show` respond with `403`.

`currentUser` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
profileImage	image	one	(optional) User's profile image, if any.
stripeAccount	stripeAccount	one	(optional) User's Stripe Account, if any.
stripeCustomer	stripeCustomer	one	(optional) User's Stripe Customer, if any. Supported nested relationships: `stripeCustomer.defaultPaymentMethod`.
effectivePermissionSet	permissionSet	one	User's final permissions, determined after considering all factors, including global settings and defaults.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show current user

HTTP request

GET /v1/api/current_user/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/current_user/show' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// requires authenticated user
sdk.currentUser.show().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": true,
      "stripePayoutsEnabled": true,
      "stripeChargesEnabled": true,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I'm Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      },
      "permissions": {
        "postListings": "permission/allow",
        "initiateTransactions": "permission/allow",
        "read": "permission/allow"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: true,
      stripePayoutsEnabled: true,
      stripeChargesEnabled: true,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I'm Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      },
      permissions: {
        postListings: "permission/allow",
        initiateTransactions: "permission/allow",
        read: "permission/allow"
      }
    }
  }
}

Query the public details of the user to whom the access token belongs.

Delete user

HTTP request

POST /v1/api/current_user/delete

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/delete?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "currentPassword": "secret-pass"
}'

sdk.currentUser.delete({
  currentPassword: "secret-pass"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": true,
      "state": null,
      "createdAt": null,
      "email": null,
      "emailVerified": false,
      "identityProviders": null,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": null,
        "lastName": null,
        "displayName": null,
        "abbreviatedName": null,
        "bio": null,
        "publicData": null,
        "protectedData": null,
        "privateData": null,
        "metadata": null
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: true,
      state: null,
      createdAt: null,
      email: null,
      emailVerified: false,
      identityProviders: null,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: null,
        lastName: null,
        displayName: null,
        abbreviatedName: null,
        bio: null,
        publicData: null,
        protectedData: null,
        privateData: null,
        metadata: null
      }
    }
  }
}

Command that deletes current user. Please note that:

The user account and all the listings the user has created will be deleted.
Personal user data will be removed according to GDPR guidelines. The messages and reviews the user has sent will not be deleted.
If the user has ongoing transactions, they will not move forward.
The user cannot receive payouts after deletion.
Payouts will not be made for any ongoing transaction involving this user, including payouts for other users.
This action is permanent.

Body parameters

Parameter	Description
currentPassword	(string) The user's current password.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	Wrong current password is provided.
403	forbidden	Trusted token is not provided.

Create user

HTTP request

POST /v1/api/current_user/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "email": "joe.dunphy@example.com",
  "password": "secret-pass",
  "firstName": "Joe",
  "lastName": "Dunphy",
  "displayName": "Dunphy Co.",
  "bio": "Hello, I am Joe.",
  "publicData": {
    "age": 27
  },
  "protectedData": {
    "phoneNumber": "+1-202-555-5555"
  },
  "privateData": {
    "discoveredServiceVia": "Twitter"
   }
}'

sdk.currentUser.create({
  email: "joe.dunphy@example.com",
  password: "secret-pass",
  firstName: "Joe",
  lastName: "Dunphy",
  displayName: "Dunphy Co.",
  bio: "Hello, I am Joe.",
  publicData: {
    age: 27
  },
  protectedData: {
    phoneNumber: "+1-202-555-5555"
  },
  privateData: {
    discoveredServiceVia: "Twitter"
  }
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Dunphy Co.",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {}
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Dunphy Co.",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {}
      }
    }
  }
}

Command that creates a new marketplace user. Can be called with anonymous access token.

When the user is created, email message is sent to the provided email address with an email verification token (or link, depending on the configured email template for your marketplace). The email verification token is valid for 48 hours.

Body parameters

Parameter	Description
email	(string, case insensitive) The user's email address. Must be a valid email address.
password	(string) The user's password. Must be between 8 and 256 characters.
firstName	(string) User's first name. Cannot be an empty string.
lastName	(string) User's last name. Cannot be an empty string.
displayName	(string, optional) User's chosen display name. Defaults to first name plus initial of last name.
bio	(string, optional) User's bio. Can be up to 5000 characters.
publicData	(object, optional) User's public data. See Extended data.
protectedData	(object, optional) User's protected data. See Extended data.
privateData	(object, optional) User's private data. See Extended data.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	email-taken	User with the given email already exists.

Create user with an identity provider

HTTP request

POST /v1/api/current_user/create_with_idp

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "idpId": "facebook",
  "idpClientId": "11223344",
  "idpToken": "aabbccdd",
  "email": "joe.dunphy@example.com",
  "firstName": "Joe",
  "lastName": "Dunphy",
  "displayName": "Dunphy Co.",
  "bio": "Hello, I am Joe.",
  "publicData": {
    "age": 27
  },
  "protectedData": {
    "phoneNumber": "+1-202-555-5555"
  },
  "privateData": {
    "discoveredServiceVia": "Twitter"
   }
}'

sdk.currentUser.createWithIdp({
  idpId: "facebook",
  idpClientId: "11223344",
  idpToken: "aabbccdd",
  email: "joe.dunphy@example.com",
  firstName: "Joe",
  lastName: "Dunphy",
  displayName: "Dunphy Co.",
  bio: "Hello, I am Joe.",
  publicData: {
    age: 27
  },
  protectedData: {
    phoneNumber: "+1-202-555-5555"
  },
  privateData: {
    discoveredServiceVia: "Twitter"
  }
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "identityProviders": {
        "facebook": {
          "userId": "11223344"
        }
      },
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Dunphy Co.",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {}
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      identityProviders: {
        facebook: {
          userId: "11223344"
        }
      },
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Dunphy Co.",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {}
      }
    }
  }
}

Command that can be used to create a new marketplace user by providing a token that has been obtained from an identity provider. Using this endpoint requires that a corresponding identity provider client has been configured for the marketplace. See identity provider clients in Console.

This endpoint be called with an anonymous Sharetribe access token.

When the user is created, if a verified email address can not be obtained from the identity provider, email message is sent with an email verification token (or link, depending on the configured email template for your marketplace). If an email address is provided in the request, the verification message is sent to that address. If not, the verification message is sent to a non-verified email address obtained from the identity provider. The email verification token is valid for 48 hours.

Body parameters

Parameter	Description
idpId	IdP ID of the identity provider client that is used to authenticate the user. See identity provider clients in Console.
idpClientId	Client ID of the identity provider client that is used to authenticate the user. See identity provider clients in Console.
idpToken	(string) A token obtained from an identity provider. See supported identity providers for more information on what token needs to be provided with a given identity provider.
email	(string, optional) The user's email address. Must be a valid email address. If not provided, a verified email address obtained from the identity provider will be used.
firstName	(string, optional) User's first name. If not provided, first name information obtained from the identity provider will be used.
lastName	(string, optional) User's last name. If not provided, last name information obtained from the identity provider will be used.
displayName	(string, optional) User's chosen display name. Defaults to first name plus initial of last name.
bio	(string, optional) User's bio. Can be up to 5000 characters.
publicData	(object, optional) User's public data. See Extended data.
protectedData	(object, optional) User's protected data. See Extended data.
privateData	(object, optional) User's private data. See Extended data.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	Not able to validate given IdP token with given IdP ID and client ID.
409	idp-profile-already-exists	IdP user ID obtained from the IdP token is already associated with a user account.
409	conflict-missing-key	A user attribute has not been provided in the request and it can not be obtained from an identity provider.
409	email-taken	User with the given email already exists.

Update user profile

HTTP request

POST /v1/api/current_user/update_profile

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/update_profile?expand=true,include=profileImage' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "firstName": "Alex",
  "bio": "Hello, this is my new bio.",
  "profileImageId": "c5b75c21-5b30-40bf-a114-4688c07128ef",
  "publicData": {
    "age": 27
  },
  "protectedData": {
    "phoneNumber": "+1-202-555-4444"
  },
  "privateData": {
    "discoveredServiceVia": "Twitter"
  }
}'

sdk.currentUser.updateProfile({
  firstName: "Alex",
  bio: "Hello, this is my new bio.",
  profileImageId: UUID {uuid: "c5b75c21-5b30-40bf-a114-4688c07128ef"},
  publicData: {
    age: 27
  },
  protectedData: {
    phoneNumber: "+1-202-555-4444"
  },
  privateData: {
    discoveredServiceVia: "Twitter"
  }
}, {
  expand: true,
  include: ["profileImage"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Alex",
        "lastName": "Dunphy",
        "displayName": "Alex D",
        "abbreviatedName": "AD",
        "bio": "Hellow, this is my new bio.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-4444"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      },
      "relationships": {
        "profileImage": {
          "data": {
            "id": "c5b75c21-5b30-40bf-a114-4688c07128ef",
            "type": "image"
          }
        }
      }
    }
  },
  "included": [{
    "id": "c5b75c21-5b30-40bf-a114-4688c07128ef",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "width": 750,
          "height": 750,
          "url": "https://www.example.com/image/c5b75c21-5b30-40bf-a114-4688c07128ef"
        }
      }
    }
  }]
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Alex",
        lastName: "Dunphy",
        displayName: "Alex D",
        abbreviatedName: "AD",
        bio: "Hellow, this is my new bio.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-4444"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      },
      relationships: {
        profileImage: {
          data: {
            id: UUID {uuid: "c5b75c21-5b30-40bf-a114-4688c07128ef"},
            type: "image"
          }
        }
      }
    }
  },
  included: [{
    id: UUID {uuid: "c5b75c21-5b30-40bf-a114-4688c07128ef"},
    type: "image",
    attributes: {
      variants: {
        default: {
          width: 750,
          height: 750,
          url: "https://www.example.com/image/c5b75c21-5b30-40bf-a114-4688c07128ef",
        }
      }
    }
  }]
}

Command that updates the authenticated user's profile information.

Body parameters

Parameter	Description
firstName	(string, optional) User's first name. Can not be empty string.
lastName	(string, optional) User's last name. Can not be empty string.
displayName	(string, optional) User's chosen display name. Passing `null` or `""` here will reset the display name to the default formed by user's first name plus initial of last name.
bio	(string, optional) User's bio. Passing `null` here will remove bio. Can be up to 5000 characters.
publicData	(object, optional) User's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB. The given `publicData` object is merged with the existing user `publicData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `publicData`.
protectedData	(object, optional) User's protected data. See Extended data. The total size of the protected data object as JSON string must not exceed 50KB. The given `protectedData` object is merged with the existing user `protectedData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `protectedData`.
privateData	(object, optional) User's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB. The given `privateData` object is merged with the existing user `privateData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the users's `privateData`.
profileImageId	(uuid, optional) Set the user's profile image. The ID must be of an image previously uploaded via the `/images/upload` API endpoint. Earlier profile image is deleted. If the value is set to `null`, the current profile image (if any) will be removed.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	image-invalid	Given image is not found or is already in use. Upload a new image.

Change password

HTTP request

POST /v1/api/current_user/change_password

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/change_password?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "currentPassword": "secret-pass",
  "newPassword": "more-secret-pass"
}'

sdk.currentUser.changePassword({
  currentPassword: "secret-pass",
  newPassword: "more-secret-pass"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      }
    }
  }
}

Command that changes the authenticated user's password.

Calls to this command require the current user password for additional authorization.

Body parameters

Parameter	Description
currentPassword	(string) The user's current password.
newPassword	(string) The new password. Must be between 8 and 256 characters.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	Wrong current password is provided.

Change email address

HTTP request

POST /v1/api/current_user/change_email

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/change_email?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "currentPassword": "secret-pass",
  "email": "joe.new@example.com"
}'

sdk.currentUser.changeEmail({
  currentPassword: "secret-pass",
  email: "joe.new@example.com"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": "joe.new@example.com",
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: "joe.new@example.com",
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      }
    }
  }
}

Command that initiates email change for the authenticated user. If the user has previously verified their email address, the response will contain the new email in the pendingEmail attribute. Otherwise, email will immediately be replaced (and emailVerified remains false).

The email change will be completed when the new address is verified via the /current_user/verify_email API endpoint.

This command sends an email message to the user, containing an email verification token or link. The token is valid for 48 hours.

Calls to this command require the current user password for additional authorization.

Body parameters

Parameter	Description
currentPassword	(string) The user's current password.
email	(string, case insensitive) The new user's email address. Must be a valid email address.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	Wrong current password is provided.
409	email-taken	The email address is already in use by another user.

Verify email address

HTTP request

POST /v1/api/current_user/verify_email

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/verify_email?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "verificationToken": "123456789"
}'

sdk.currentUser.verifyEmail({
  verificationToken: "123456789"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": true,
      "pendingEmail": null,
      "stripeConnected": false,
      "stripePayoutsEnabled": false,
      "stripeChargesEnabled": false,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        },
        "metadata": {
          "verified": true
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: true,
      pendingEmail: null,
      stripeConnected: false,
      stripePayoutsEnabled: false,
      stripeChargesEnabled: false,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        },
        metadata: {
          verified: true
        }
      }
    }
  }
}

Command that marks user's current or pending email as verified. If the user had a pendingEmail (i.e. they initiated email change via /current_user/change_email), then that email becomes the new primary email for the user.

Body parameters

Parameter	Description
verificationToken	(string) The email verification token.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	The email verification token is invalid or has expired.

Send verification email

HTTP request

POST /v1/api/current_user/send_verification_email

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/send_verification_email' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.currentUser.sendVerificationEmail().then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser"
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser"
  }
}

Command that sends an email message with a new email verification token to the user, if the user has an unverified email address. The email verification token is valid for 48 hours.

Common errors

HTTP status code	Error code	Description
409	email-already-verified	The email address has already been verified.

DEPRECATED: Create Stripe account

HTTP request

POST /v1/api/current_user/create_stripe_account

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/create_stripe_account?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "country": "US",
  "accountToken": "ct_stripeaccounttoken",
  "bankAccountToken": "tok_stripebanktoken"
}'

sdk.currentUser.createStripeAccount({
  country: "US",
  accountToken: "ct_stripeaccounttoken",
  bankAccountToken: "tok_stripebanktoken"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": true,
      "stripePayoutsEnabled": true,
      "stripeChargesEnabled": true,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: true,
      stripePayoutsEnabled: true,
      stripeChargesEnabled: true,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        }
      }
    }
  }
}

Command for creating a Stripe account for the user. Users need to have a Stripe account with a bank account set up (i.e. bankAccountToken provided) before others can initiate transactions with them.

Body parameters

Parameter	Description
country	(string) Country of residence. ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`, `FR`, etc).
accountToken	(string) Stripe account token for the user's legal entity details. API clients need to obtain the token via the Stripe API, through the same Stripe platform account as the one used by the marketplace.
bankAccountToken	(string, optional) Stripe bank account token for the user. API clients need to obtain the token via Stripe API, through the same Stripe platform account as the one used by the marketplace.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

DEPRECATED: Update Stripe account

HTTP request

POST /v1/api/current_user/update_stripe_account

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/current_user/update_stripe_account?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "accountToken": "ct_anotheraccounttoken",
  "bankAccountToken": "tok_anotherstripebanktoken"
}'

sdk.currentUser.updateStripeAccount({
  accountToken: "tok_anotheraccounttoken",
  bankAccountToken: "tok_anotherstripebanktoken"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
    "type": "currentUser",
    "attributes": {
      "banned": false,
      "deleted": false,
      "state": "active",
      "createdAt": "2018-03-28T09:12:58.866Z",
      "email": "joe.dunphy@example.com",
      "emailVerified": false,
      "pendingEmail": null,
      "stripeConnected": true,
      "stripePayoutsEnabled": true,
      "stripeChargesEnabled": true,
      "profile": {
        "firstName": "Joe",
        "lastName": "Dunphy",
        "displayName": "Joe D",
        "abbreviatedName": "JD",
        "bio": "Hello, I am Joe.",
        "publicData": {
          "age": 27
        },
        "protectedData": {
          "phoneNumber": "+1-202-555-5555"
        },
        "privateData": {
          "discoveredServiceVia": "Twitter"
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
    type: "currentUser",
    attributes: {
      banned: false,
      deleted: false,
      state: "active",
      createdAt: new Date("2018-03-28T09:12:58.866Z"),
      email: "joe.dunphy@example.com",
      emailVerified: false,
      pendingEmail: null,
      stripeConnected: true,
      stripePayoutsEnabled: true,
      stripeChargesEnabled: true,
      profile: {
        firstName: "Joe",
        lastName: "Dunphy",
        displayName: "Joe D",
        abbreviatedName: "JD",
        bio: "Hello, I am Joe.",
        publicData: {
          age: 27
        },
        protectedData: {
          phoneNumber: "+1-202-555-5555"
        },
        privateData: {
          discoveredServiceVia: "Twitter"
        }
      }
    }
  }
}

Command for updating the Stripe account for the user. Users need to have Stripe account with a bank account set up (i.e. bankAccountToken provided) before others can initiate transactions with them.

Body parameters

Parameter	Description
accountToken	(string, optional) Stripe account token for the user's legal entity details. API clients need to obtain the token via the Stripe API, through the same Stripe platform account as the one used by the marketplace.
bankAccountToken	(string, optional) Stripe bank account token for the user. API clients need to obtain the token via Stripe API, through the same Stripe platform account as the one used by the marketplace.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Password reset

API prefix

/v1/api/password_reset/

Example resource

{
  "data": {
    "id": "04dea6b2-f7af-4896-b6df-aaabf012a80e",
    "type": "passwordReset",
    "attributes": {}
  }
}

{
  data: {
    id: UUID {uuid: "04dea6b2-f7af-4896-b6df-aaabf012a80e"},
    type: "passwordReset",
    attributes: {}
  }
}

The passwordReset API resource type represents responses to /password_reset/* commands.

Request password reset

HTTP request

POST /v1/api/password_reset/request

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/password_reset/request' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "email": "joe.dunphy@example.com"
}'

sdk.passwordReset.request({
  email: "joe.dunphy@example.com"
}, {}).then(res => {
  // res.data
});

Example responses

{
  "data": {
    "id": "04dea6b2-f7af-4896-b6df-aaabf012a80e",
    "type": "passwordReset"
  }
}

{
  data: {
    id: UUID {uuid: "04dea6b2-f7af-4896-b6df-aaabf012a80e"},
    type: "passwordReset"
  }
}

Command that initiates password reset for the marketplace user with the given email address.

If a user with the email exists in the marketplace, an email containing a password reset token is sent to them.

Body parameters

Parameter	Description
email	(string, case insensitive) The email address of the user to reset the password for.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	email-not-found	User with given email is not found in the marketplace.

Reset password

HTTP request

POST /v1/api/password_reset/reset

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/password_reset/reset' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "email": "joe.dunphy@example.com",
  "passwordResetToken": "YOUR_TOKEN",
  "newPassword": "a-password-that-shant-be-forgotten"
}'

sdk.passwordReset.reset({
  email: "joe.dunphy@example.com",
  passwordResetToken: "YOUR_TOKEN",
  newPassword: "a-password-that-shant-be-forgotten"
}, {}).then(res => {
  // res.data
});

Example responses

{
  "data": {
    "id": "852e1b31-dc67-438b-8ef4-c1b75845c0b6",
    "type": "passwordReset"
  }
}

{
  data: {
    id: UUID {uuid: "852e1b31-dc67-438b-8ef4-c1b75845c0b6"},
    type: "passwordReset"
  }
}

Command that resets the user's password using a password reset token, obtained by calling /password_reset/request command.

Body parameters

Parameter	Description
email	(string, case insensitive) The email address of the user to reset the password for.
passwordResetToken	(string) The password reset token.
newPassword	(string) The new password. Must be between 8 and 256 characters.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	The password reset token is invalid or does not match the given email address.

Stripe Account

API prefix

/v1/api/stripe_account/

Example resource

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG",
      "stripeAccountData": {
        # Stripe Account data
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG",
      stripeAccountData: {
        // Stripe Account Data
      }
    }
  }
}

The stripeAccount resource type represents details about the Stripe account of the authenticated user.

All stripe_account/ API endpoints require an authenticated user access token.

`stripeAccount` resource format

Attribute	Description
stripeAccountId	(string) Stripe's own ID for the Stripe Account.
stripeAccountData	(object, nullable) Account object returned from Stripe. See the Stripe API docs on Accounts for a description of a Custom Account object.

Fetch Stripe account

HTTP request

POST /v1/api/stripe_account/fetch

Example request

$ curl -X GET 'https://flex-api.sharetribe.com/v1/api/stripe_account/' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.stripeAccount.fetch().then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG",
      "stripeAccountData": {
        # Stripe Account data
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG",
      stripeAccountData: {
        // Stripe Account Data
      }
    }
  }
}

Fetch Stripe account information of the authenticated user. Calling this endpoint performs a request to the Stripe API.

Create Stripe account

HTTP request

POST /v1/api/stripe_account/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_account/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "country": "US",
  "businessProfileMCC": "7394",
  "businessProfileURL": "http://www.example.com/user/joe",
  "accountToken": "ct_stripeaccounttoken",
  "bankAccountToken": "tok_stripebanktoken"
}'

sdk.stripeAccount.create({
  country: "US",
  businessProfileMCC: "7394",
  businessProfileURL: "http://www.example.com/user/joe",
  accountToken: "ct_stripeaccounttoken",
  bankAccountToken: "tok_stripebanktoken"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG",
      "stripeAccountData": {
        # Stripe Account data
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG",
      stripeAccountData: {
        // Stripe Account Data
      }
    }
  }
}

Command for creating a Stripe Connect Custom account for the user. Users need to have a Stripe account with a bank account set up (i.e. bankAccountToken provided) before others can initiate transactions with them successfully.

Body parameters

Parameter	Description
country	(string) Country of residence. ISO 3166-1 alpha-2 country code (e.g. `US`, `DE`, `FR`, etc).
accountToken	(string, optional) Stripe account token created with the account's details. API clients need to obtain the token via the Stripe API, through the same Stripe platform account as the one used by the marketplace.
bankAccountToken	(string, optional) Stripe bank account token for the user. API clients need to obtain the token via Stripe API, through the same Stripe platform account as the one used by the marketplace.
businessProfileMCC	(string, optional) Merchant Category Code (MCC) for the Stripe Account. This is required information for US accounts in order for the account to pass Stripe's verification.
businessProfileURL	(string, optional) Business URL.
businessProfileProductDescription	(string, optional) Business' product description.
requestedCapabilities	(array, optional) Requested capabalities for the account. Dependendent on the Stripe API version in use. You can check the Stripe API version in use from Console and use the `flex-cli` to update your Stripe API version. Default values for Stripe API version `2019-12-03` and newer are `["card_payments", "transfers", "legacy_payments"]`. `legacy_payments` are removed in the future when they are not anymore supported by Stripe.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Supported Stripe API versions:

2019-12-03
2019-09-09
2019-02-19.

As of writing, US Stripe individual and business accounts need to provide at least one of businessProfileURL or businessProfileProductDescription in order for the account to pass Stripe's verification. For up-to-date information on required account data, see Stripe's documentation.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Update Stripe account

HTTP request

POST /v1/api/stripe_account/update

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_account/update?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "businessProfileMCC": "4457",
  "accountToken": "ct_newstripeaccounttoken",
  "bankAccountToken": "tok_newstripebanktoken"
}'

sdk.stripeAccount.update({
  businessProfileMCC: "4457",
  accountToken: "ct_newstripeaccounttoken",
  bankAccountToken: "tok_newstripebanktoken"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "cb5e8305-67f0-4d04-a081-954411eaf6b9",
    "type": "stripeAccount",
    "attributes": {
      "stripeAccountId": "acct_1EHoPgDktN4RYwdG",
      "stripeAccountData": {
        # Stripe Account data

    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "cb5e8305-67f0-4d04-a081-954411eaf6b9"},
    type: "stripeAccount",
    attributes: {
      stripeAccountId: "acct_1EHoPgDktN4RYwdG",
      stripeAccountData: {
        // Stripe Account Data
      }
    }
  }
}

Body parameters

Parameter	Description
accountToken	(string, optional) Stripe account token created with the account's details. API clients need to obtain the token via the Stripe API, through the same Stripe platform account as the one used by the marketplace.
bankAccountToken	(string, optional) Stripe bank account token for the user. API clients need to obtain the token via Stripe API, through the same Stripe platform account as the one used by the marketplace.
businessProfileMCC	(string, optional) Merchant Category Code (MCC) for the Stripe Account. This is required information for US accounts in order for the account to pass Stripe's verification.
businessProfileURL	(string, optional) Business URL.
businessProfileProductDescription	(string, optional) Business' product description.
requestedCapabilities	(array, optional) Requested capabalities for the account. Dependendent on the Stripe API version in use. You can check the Stripe API version in use from Console and use the `flex-cli` to update your Stripe API version.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Supported Stripe API versions:

2019-12-03
2019-09-09
2019-02-19.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-account-not-found	The provider has not set up a Stripe account.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Stripe Account Links

API prefix

/v1/api/stripe_account_links/

Example resource

{
  "data": {
    "id": "a6a42419-92b1-4036-bf7d-b5ea21f1bf18",
    "type": "stripeAccountLink",
    "attributes": {
      "url": "https://connect.stripe.com/setup/c/zMlgtdGM6eyy",
      "expiresAt": "2019-12-05T08:31:51.000Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "a6a42419-92b1-4036-bf7d-b5ea21f1bf18"},
    type: "stripeAccountLink",
    attributes: {
      url: "https://connect.stripe.com/setup/c/zMlgtdGM6eyy",
      expiresAt: "2019-12-05T08:31:51.000Z"
    }
  }
}

The stripeAccountLink resource type represents details about a Stripe Account Link. An account link can be used for sending user to Stripe Connect Onboarding UI.

All stripe_account_links/ API endpoints require an authenticated user access token.

As all API resources, stripeAccountLink resources have IDs. However, their IDs are ephemeral and will change across requests.

`stripeAccountLink` resource format

Attribute	Description
url	(string) The URL to Stripe Connect Onboarding user interface
expiresAt	(string, timestamp) The date and time when the Account Link will expire in ISO 8601 format.

Create Stripe Account Link

HTTP request

POST /v1/api/stripe_account_links/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_account_links/create'
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "failureURL": "https://www.example.com/failure",
  "successURL": "https://www.example.com/success",
  "type": "custom_account_verification",
  "collectionOptions": { "fields": "currently_due", "future_requirements": "omit" },
}'

sdk.stripeAccountLinks.create({
  failureURL: "https://www.example.com/failure",
  successURL: "https://www.example.com/success",
  type: "custom_account_verification",
  collectionOptions: { fields: "currently_due", future_requirements: "omit" },
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "a6a42419-92b1-4036-bf7d-b5ea21f1bf18",
    "type": "stripeAccountLink",
    "attributes": {
      "url": "https://connect.stripe.com/setup/c/zMlgtdGM6eyy",
      "expiresAt": "2019-12-05T08:31:51.000Z"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "a6a42419-92b1-4036-bf7d-b5ea21f1bf18"},
    type: "stripeAccountLink",
    attributes: {
      url: "https://connect.stripe.com/setup/c/zMlgtdGM6eyy",
      expiresAt: "2019-12-05T08:31:51.000Z"
    }
  }
}

As all API resources, stripeAccountLink resources have IDs. However, their IDs are ephemeral and will change across requests.

Command for creating a Stripe Account Link for the user.

Body parameters

Parameter	Description
failureURL	(string) The URL for redirecting user in failure cases from the Stripe UI.
successURL	(string) The URL for redirecting user in success cases from the Stripe UI.
type	(string) The type of Account Link the user is requesting. See Stripe API reference and Connect Onboarding documentation for possible values.
collectionOptions	(object, optional) Specifies the requirements for the details that Stripe collects in the Onboarding flow. Note that the object is passed to Stripe's API directly and follows Stripe API conventions (e.g. uses snake_case). See Stripe API reference and Connect Onboarding documentation for possible values.
collect (DEPRECATED)	(string, optional) String determining the information the Stripe Connect Onboarding needs to collect from the user. See Stripe API reference and Connect Onboarding documentation for possible values. DEPRECATED: use `collectionOptions` instead.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-account-not-found	The authenticated user does not have a Stripe account created. Call `stripe_accounts/create` first.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Stripe Persons

API prefix

/v1/api/stripe_persons/

Example resource

{
  "data": {
    "id": "260cfa5a-2a59-4c71-96ce-8ad58e1d59ae",
    "type": "stripePerson",
    "attributes": {
      "stripePersonId": "person_ElL6AmATh7u73E"
    }
  }
}

{
  data: {
    id: UUID {uuid: "260cfa5a-2a59-4c71-96ce-8ad58e1d59ae"},
    type: "stripePerson",
    attributes: {
      stripePersonId: "person_ElL6AmATh7u73E"
    }
  }
}

The stripePerson resource type represents details about a Stripe Person associated with the authenticated user's Stripe Account.

As all API resources, stripePerson resources have IDs. However, their IDs are ephemeral and will change across requests.

All stripe_persons/ API endpoints require an authenticated user access token.

`stripeAccount` resource format

Attribute	Description
stripePersonId	(string) The Stripe's own ID for the Stripe Person.

Create Stripe person

HTTP request

POST /v1/api/stripe_persons/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_persons/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "personToken": "tok_stripepersontoken"
}'

sdk.stripePersons.create({
  personToken: "tok_stripepersontoken"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "260cfa5a-2a59-4c71-96ce-8ad58e1d59ae",
    "type": "stripePerson",
    "attributes": {
      "stripePersonId": "person_ElL6AmATh7u73E"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "260cfa5a-2a59-4c71-96ce-8ad58e1d59ae"},
    type: "stripePerson",
    attributes: {
      stripePersonId: "person_ElL6AmATh7u73E"
    }
  }
}

Command for adding a new Stripe Person to the authenticated user's Stripe Account when the account was created as Stripe Business account. Stripe Business accounts need to have Persons added so that they pass Stripe's verification.

Body parameters

Parameter	Description
personToken	(string) Stripe person token, created with all the necessary information for the Stripe Person. API clients need to obtain the token via Stripe API, through the same Stripe platform account as the one used by the marketplace.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-account-not-found	The provider has not set up a Stripe account.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Stripe Setup Intents

API prefix

/v1/api/stripe_setup_intents/

Example resource

{
  "data": {
    "id": "5d2db7ba-f902-426b-a0a2-a94b3886a825",
    "type": "stripeSetupIntent",
    "attributes": {
      "stripeSetupIntentId": "seti_1Ewp1XXXXXXGQQ9xoFZb4Ypn",
      "clientSecret": "seti_1Ewp1SLSea1GQQ9xoFZb4Ypn_secret_foo"
    }
  }
}

{
  data: {
    id: UUID {uuid: "5d2db7ba-f902-426b-a0a2-a94b3886a825"},
    type: "stripeSetupIntent",
    attributes: {
      stripeSetupIntentId: "seti_1Ewp1XXXXXXGQQ9xoFZb4Ypn",
      clientSecret: "seti_1Ewp1SLSea1GQQ9xoFZb4Ypn_secret_foo"
    }
  }
}

The stripeSetupIntent resource type represents details about a Stripe SetupIntent. SetupIntents are used when storing payment card details for future reuse, without performing a payment at the same time.

All stripe_setup_intents/ API endpoints require an authenticated user access token.

`stripeSetupIntent` resource format

Attribute	Description
stripeSetupIntentId	(string) Stripe's own ID for the SetupIntent.
clientSecret	(string) The SetupIntent's client secret. It can be used to handle the SetupIntent client-side using Stripe.js SDK.

Create Stripe Setup Intents

HTTP request

POST /v1/api/stripe_setup_intents/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_setup_intents/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.stripeSetupIntents.create({}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5d2db7ba-f902-426b-a0a2-a94b3886a825",
    "type": "stripeSetupIntent",
    "attributes": {
      "stripeSetupIntentId": "seti_1Ewp1XXXXXXGQQ9xoFZb4Ypn",
      "clientSecret": "seti_1Ewp1SLSea1GQQ9xoFZb4Ypn_secret_foo"
    }
  }
}

// res.data
{
    data: {
        id: UUID {uuid: "5d2db7ba-f902-426b-a0a2-a94b3886a825"},
        type: "stripeSetupIntent",
        attributes: {
            stripeSetupIntentId: "seti_1Ewp1XXXXXXGQQ9xoFZb4Ypn",
            clientSecret: "seti_1Ewp1SLSea1GQQ9xoFZb4Ypn_secret_foo"
        }
    }
}

Create a new Stripe SetupIntent. The client can then use the SetupIntent to create a Stripe PaymentMethod in an SCA-compatible way using Stripe.js SDK.

Body parameters

This API endpoint does not require any parameters.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stripe Customer

API prefix

/v1/api/stripe_customer/

Example resource

{
  "data": {
    "id": "5d08c886-8016-4e84-aef7-2feabf5a97bf",
    "type": "stripeCustomer",
    "attributes": {
      "stripeCustomerId": "cus_FHDmFZScwuoEvY"
    }
  }
}

{
  data: {
    id: UUID {uuid: "5d08c886-8016-4e84-aef7-2feabf5a97bf"},
    type: "stripeCustomer",
    attributes: {
      stripeCustomerId: "cus_FHDmFZScwuoEvY"
    }
  }
}

The stripeCustomer resource type represents details about the Stripe customer related to the authenticated user.

At the moment there are no /show or /query endpoints for this resource but it can be obtained via the /current_user/show endpoint as stripeCustomer is a relationship of the currentUser resource.

All stripe_customer/ API endpoints require an authenticated user access token.

`stripeCustomer` resource format

Attribute	Description
stripeCustomerId	(string) Stripe's own ID for the Stripe customer.

`stripeCustomer` relationships

Relationship	Resource type	Cardinality	Description
defaultPaymentMethod	stripePaymentMethod	one	Default payment method set for the Stripe customer.

Create Stripe customer

HTTP request

POST /v1/api/stripe_customer/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_customer/create?expand=true&include=defaultPaymentMethod' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "stripePaymentMethodId": "pm_1EmfL3LSea1GQQ9xudUuun1q"
}'

sdk.stripeCustomer.create({
  stripePaymentMethodId: "pm_1EmfL3LSea1GQQ9xudUuun1q"
}, {
  expand: true,
  include: "defaultPaymentMethod"
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5d08c886-8016-4e84-aef7-2feabf5a97bf",
    "type": "stripeCustomer",
    "attributes": {
      "stripeCustomerId": "cus_FHDmFZScwuoEvY"
    },
    "relationships": {
      "defaultPaymentMethod": {
        "data": {
          "id": "5d0a1d78-5204-4868-9464-0791ea5a47c5",
          "type": "stripePaymentMethod"
        }
      }
    }
  },
  "included": [
    {
      "id": "5d0a1d78-5204-4868-9464-0791ea5a47c5",
      "type": "stripePaymentMethod",
      "attributes": {
        "type": "stripe-payment-method/card",
        "stripePaymentMethodId": "pm_1En22LLSea1GQQ9xvcW6iZLr",
        "card": {
          "brand": "visa",
          "last4Digits": "4242",
          "expirationYear": 2020,
          "expirationMonth": 6
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "5d08c886-8016-4e84-aef7-2feabf5a97bf"},
    type: "stripeCustomer",
    attributes: {
      stripeCustomerId: "cus_FHDmFZScwuoEvY"
    }
    relationships: {
      defaultPaymentMethod: {
        data: {
          id: UUID {uuid: "5d0a1d78-5204-4868-9464-0791ea5a47c5"},
          type: "stripePaymentMethod"
        }
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "5d0a1d78-5204-4868-9464-0791ea5a47c5"},
      type: "stripePaymentMethod",
      attributes: {
        type: "stripe-payment-method/card",
        stripePaymentMethodId: "pm_1En22LLSea1GQQ9xvcW6iZLr",
        card: {
          brand: "visa",
          last4Digits: "4242",
          expirationYear: 2020,
          expirationMonth: 6
        }
      }
    }
  ]
}

Command for creating a Stripe customer for the authenticated user.

Optionally accepts an ID of a Stripe Payment Method as a parameter. Attaches the payment method to the newly created Stripe Customer and sets it as the default payment method.

Note that in order to store card details in an SCA-compatible way, the Stripe PaymentMethod needs to be either set up using stripeSetupIntent or during a transaction in an SCA-compatible transaction process. For details, see Using stored payment cards.

If a Stripe Customer is already attached to the user the existing stripeCustomer resource is returned.

Body parameters

Parameter	Description
stripePaymentMethodId	(string, optional) Stripe payment method ID.
stripeCustomerEmail	(string, optional) Email address to be passed to Stripe for the customer. This email address is not stored in Sharetribe or used by Sharetribe directly.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-payment-method-type-not-supported	The provided payment method is not supported. Currenlty only card payment methods are allowed.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Add payment method

HTTP request

POST /v1/api/stripe_customer/add_payment_method

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_customer/add_payment_method?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "stripePaymentMethodId": "pm_1EmfL3LSea1GQQ9xudUuun1q"
}'

sdk.stripeCustomer.addPaymentMethod({
  stripePaymentMethodId: "pm_1EmfL3LSea1GQQ9xudUuun1q"
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5d08c886-8016-4e84-aef7-2feabf5a97bf",
    "type": "stripeCustomer",
    "attributes": {
      "stripeCustomerId": "cus_FHDmFZScwuoEvY"
    }
  }
}

// res.data


{
  data: {
    id: UUID {uuid: "5d08c886-8016-4e84-aef7-2feabf5a97bf"},
    type: "stripeCustomer",
    attributes: {
      stripeCustomerId: "cus_FHDmFZScwuoEvY"
    }
  }
}

Command for adding a payment method for a Stripe customer. The payment method is set as the default payment method. Currently only one payment method is supported at a time.

Body parameters

Parameter	Description
stripePaymentMethodId	(string) Stripe payment method ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-customer-not-found	No Stripe customer is found for the user.
409	stripe-multiple-payment-methods-not-supported	User's Stripe customer already has a payment method.
409	stripe-payment-method-type-not-supported	The provided payment method is not supported. Currenlty only card payment methods are allowed.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

Delete payment method

HTTP request

POST /v1/api/stripe_customer/delete_payment_method

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stripe_customer/delete_payment_method?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \

sdk.stripeCustomer.deletePaymentMethod({}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5d08c886-8016-4e84-aef7-2feabf5a97bf",
    "type": "stripeCustomer",
    "attributes": {
      "stripeCustomerId": "cus_FHDmFZScwuoEvY"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "5d08c886-8016-4e84-aef7-2feabf5a97bf"},
    type: "stripeCustomer",
    attributes: {
      stripeCustomerId: "cus_FHDmFZScwuoEvY"
    }
  }
}

Command for removing a payment method from a Stripe customer.

Common errors

HTTP status code	Error code	Description
400	validation-invalid-params	An invalid set of parameters is sent in the request. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).
409	stripe-customer-not-found	No Stripe customer is found for the authenticated user.
409	stripe-invalid-request	A request to Stripe was unacceptable for an unspecified reason. See error `meta` object for details from Stripe (`stripeMessage`, `stripeCode`, `stripeDeclineCode`).

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stripe Payment Method

Example resource

{
  "data": {
    "id": "5d0a1d78-5204-4868-9464-0791ea5a47c5",
    "type": "stripePaymentMethod",
    "attributes": {
      "type": "stripe-payment-method/card",
      "stripePaymentMethodId": "pm_1En22LLSea1GQQ9xvcW6iZLr",
      "card": {
        "brand": "visa",
        "last4Digits": "4242",
        "expirationYear": 2020,
        "expirationMonth": 6
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "5d0a1d78-5204-4868-9464-0791ea5a47c5"},
    type: "stripePaymentMethod",
    attributes: {
      type: "stripe-payment-method/card",
      stripePaymentMethodId: "pm_1En22LLSea1GQQ9xvcW6iZLr",
      card: {
        brand: "visa",
        last4Digits: "4242",
        expirationYear: 2020,
        expirationMonth: 6
      }
    }
  }
}

The stripePaymentMethod resource type represents details about a Stripe payment method. Currently only payment cards are supported as payment methods.

At the moment there are no /show or /query endpoints for this resource but it can be obtained via the /current_user/show endpoint as defaultPaymentMethod is a nested relationship of the currentUser resource.

For adding and removing payment methods, see the /stripe_customer endpoints.

`stripeCustomer` resource format

Attribute	Description
type	(string) Type of the payment method. Currently only `stripe-payment-method/card` is supported.
stripePaymentMethodId	(string) Stripe's own ID for the payment method.
card.brand	(string) Payment card brand name (as returned by Stripe).
card.last4Digits	(string) Last four digits of the card number.
card.expirationYear	(number) Expiration year of the card.
card.expirationMonth	(number) Expiration month of the card.

Listings

API prefix

/v1/api/listings/

Example resource

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

The listing API resource type represents public information about listings in the marketplace.

`listing` resource format

Attribute	Description
title	(string) Listing's title.
description	(string) Listing's description.
geolocation	(object, location) Latitude (`lat`) and longitude (`lng`) of the listing's location.
createdAt	(string, timestamp) The date and time when the listing was created in ISO 8601 format.
price	(object, money) Listing's unit price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object) Listing's availability plan. See `listing` availability plan.
publicData	(object) Listing's public data. See Extended data.
metadata	(object) Listing's public metadata. See Extended data.
state	(string) The listing's current state. See Listing states.
deleted	(boolean) Flag indicating whether the listing has been deleted. If `true`, all other attributes of the listing will be returned as default values (`false` for booleans and `null` for all else).

`listing` states

A listing resource type may be in one of the following states:

State Description

published Listing is published and discoverable via the /listings/query API endpoint.

closed A published listing can be closed by its author or a marketplace operator. Closed listings are not returned in search results or public listing queries and new transactions can not be initiated with them, but they can still be accessed as own listings or via the listing ID, or when related to another known resource (such as transaction). The intention of closing a listing is not to delete it, but to stop advertising it. A closed listing can be reopened, which sets it in published state again.

`listing` availability plan

The listing resource's availabilityPlan attribute contains the type and, in case of time-based availability plans, the timezone of the listing's availability plan. The availability plan entries are not included. To query the concrete time slots available for booking, use the /timeslots/query API endpoint. For more information, see ownListing availability plan.

Attribute	Description
type	(string) Availability plan type. Possible types are `availability-plan/day` for day-based availability and `availability-plan/time` for time-based availability.
timezone	(string) Only for the `availability-plan/time` type. Time zone in which the plan is set. Supports time zone names from the TZ time zone database, for example "Europe/Berlin". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.

`listing` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the user.
author	user	one	The marketplace user, to whom the listing belongs. Supported nested relationships: `author.profileImage`.
images	image	many	(optional) The ordered list of listing images, if any.
currentStock	stock	one	(optional) The listing's currently available stock, if set.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show listing

HTTP request

GET /v1/api/listings/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
sdk.listings.show({id: listingId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Query the public details of a given listing.

Query parameters

Parameter	Description
id	The ID of the listing.

Query listings

HTTP request

GET /v1/api/listings/query

Example request

# Search all listings, ordered by distance from given location,
# matching only listings with `publicData.gears` less than 23
# and price amount between 14.00 and 16.00.
$ curl 'https://flex-api.sharetribe.com/v1/api/listings/query?origin=40.00,-74.00&price=1400,1600&pub_gears=,23' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Search all listings, ordered by distance from given location,
// matching only listings with `publicData.gears` less than 23
// and price amount between 14.00 and 16.00.
var origin = new LatLng(40.0, -74.0);
sdk.listings.query({
  origin: origin,
  price: "1400,1600",
  pub_gears: ",23"
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "listing",
      "attributes": {
        "description": "7-speed Hybrid",
        "deleted": false,
        "geolocation": {
          "lat": 40.64542,
          "lng": -74.08508
        },
        "createdAt": "2018-03-23T08:40:24.443Z",
        "state": "published",
        "title": "Peugeot eT101",
        "availabilityPlan": {
          "type": "availability-plan/day"
        },
        "publicData": {
          "address": {
            "city": "New York",
            "country": "USA",
            "state": "NY",
            "street": "230 Hamilton Ave"
          },
          "category": "road",
          "gears": 22,
          "rules": "This is a nice, bike! Please, be careful with it."
        },
        "metadata": {
          "promoted": true
        },
        "price": {
          "amount": 1590,
          "currency": "USD"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 1014,
    "totalPages": 11,
    "page": 1,
    "perPage": 100
  }
}

{
  data: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "listing",
      attributes: {
        description: "7-speed Hybrid",
        deleted: false,
        geolocation: LatLng {lat: 40.64542, lng: -74.08508},
        createdAt: new Date("2018-03-23T08:40:24.443Z"),
        state: "published",
        title: "Peugeot eT101",
        availabilityPlan: {
          type: "availability-plan/day"
        },
        publicData: {
          address: {
            city: "New York",
            country: "USA",
            state: "NY",
            street: "230 Hamilton Ave"
          },
          category: "road",
          gears: 22,
          rules: "This is a nice, bike! Please, be careful with it."
        },
        metadata: {
          promoted: true
        },
        price: Money {amount: 1590, currency: "USD"}
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 1014,
    totalPages: 11,
    page: 1,
    perPage: 100
  }
}

Query published marketplace listings. Returns 0 or more results.

In general, this query does not return listings that are in the closed state. Depending on search indexing, however, the results may temporarily include listings that have recently been deleted or closed.

Query parameters

Parameter	Description
authorId	(uuid) Match only listings belonging to given user ID.
ids	(comma separated list of uuids, optional) List of uuids. Match only listings with an ID contained in the given list. A maximum of 100 IDs can be given.
keywords	(string) Narrow down and sort search results based on given keywords. The keywords are matched against listing title, description and optionally also specific `publidData` fields with type `text` defined in the listing public data schema of a marketplace. Can not be combined with the `origin` parameter.
origin	Search listings, based on given location. The location is given as comma-separated tuple of latitude and longitude values (e.g. `40.12,-70.3345`). The listings in the query result are sorted by distance from the given origin. Can not be combined with the `keywords` parameter.
bounds	Match only listings within a bounding box. The bounding box is given as comma-separated list of four coordinate values: NE lat, NE, lng, SW lat and SW lng. E.g. `43.0,-73.0,40.0,-77.0`.
price	(integer or integer range) Match only listings with price amount within given range. The amounts must be given as integers in the currency's minor unit (e.g. cents for USD). The currency of the listing price has no effect on the query. See Price filtering below for range syntax.
start	(timestamp) Start time of the availability interval to match listings against in ISO 8601 format. The start time must be between one day in the past and 365 days in the future. If omitted, the listings' availability data is ignored in the query. See Availability filtering below.
end	(timestamp) End time of the availability interval to match listings against (exclusive) in ISO 8601 format. The end time must be after the `start` time and must be at most 365 days in the future or at most 90 days from the `start` time (whichever comes sooner). See Availability filtering below.
seats	(integer) The number of seats a listing must have available at minimum on the given interval to to match the search criteria. See Availability filtering below. Default value is `1`.
availability	(string) The type of availability search. Accepts values: `day-full`, `day-partial`, `time-full` or `time-partial`. Default value is: `day-full`. DEPRECATED values `full` and `partial` are equivalent to `day-full` and `day-partial`, respectively. See Availability filtering below.
minDuration	(integer) Match only listings with an availability interval of at least this duration within the query range specified by `start` and `end`. Only supported when `availability` is set to either `day-partial` and `time-partial`. For `day-partial` queries, the value of `minDuration` is in days. For `time-partial` queries, the value of `minDuration` is in minutes. Default value is `0`, i.e. any duration of availability matches.
stockMode	(string) The type of stock query. Control whether listing queries using `minStock` match listings without any defined stock. The value must be one of `strict` (the default) or `match-undefined`. If `strict`, only listings that have explicitly defined stock quantity will match. If `match-undefined`, the query will also match listings without any set stock.
minStock	(integer) Match only listings that have current stock quantity equal to or greater than the given integer number. If `stockMode` is set to `match-undefined`, the query will also match any listings without a defined stock quantity.
pub_*	Query listings by `publicData` attribute(s). See Extended data filtering below.
meta_*	Query listings by `metadata` attribute(s). See Extended data filtering below.
sort	(string) Specify sort criteria. Can not be used in combination with the `origin` query parameter. Default is `createdAt` See Sorting below.

Price filtering

price range can be specified as:

Query syntax	Description
`price=VALUE`	Match listings that have price amount exactly equal to `VALUE`.
`price=START,END`	Match listings that have price amount greater than or equal to `START` and less than `END`.
`price=START,`	Match listings that have price amount greater than or equal to `START`.
`price=,END`	Match listings that have price amount less than `END`.

Extended data filtering

Queries for publicData and metadata attributes can be done only when extended data schema is defined for the attribute. Only top-level extended data attributes may have schema and are queriable, even though the extended data can be deeply nested. The supported schema types and query semantics are given below (use meta_ instead of pub_ for queries based on metadata):

Schema type	Schema cardinality	Query syntax	Description
enum	one	pub_`ATTRIBUTE_KEY`=`VALUE1,[VALUE2[,...]]`	Match listings that have any of the given values as the exact value of `ATTRIBUTE_KEY` (i.e. `OR` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`has_all:VALUE1[,VALUE2[,...]]`	Match listings that have all given values for the given multi-enum `ATTRIBUTE_KEY` (i.e. `AND` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`VALUE1[,VALUE2[,...]]`	Same as `has_all:`, we use `AND` semantics by default.
enum	many	pub_`ATTRIBUTE_KEY`=`has_any:VALUE1[,VALUE2[,...]]`	Match listings that have any of the given values for the multi-enum `ATTRIBUTE_KEY` (i.e. `OR` semantics).
long	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is exactly equal to `VALUE`.
long	one	pub_`ATTRIBUTE_KEY`=`START,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START` and less than `END`.
long	one	pub_`ATTRIBUTE_KEY`=`START,`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START`.
long	one	pub_`ATTRIBUTE_KEY`=`,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is less than `END`.
boolean	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is equal to `VALUE`.
text	one	keywords=`KEYWORDS`	Match and sort listings that have a string from `KEYWORDS` in listing title, description or extended data attributes with type `text`.

Availability filtering

The availability filtering is controlled by the following query parameters: start, end, availability, seats and minDuration. The following rules apply:

When availability is set to either day-full or day-partial, only listings with a day-based availability plan are matched.
When availability is set to time-full or time-partial, only listings with time-based availability plans are matched.
day-full and time-full availability queries match only listings that have availability with the required number of seats for the entire duration of the query range (specified by start and end).
day-partial and time-partial availability queries match only listings that have some availability with the required number of seats and minDuration for the given query range (specified by start and end). minDuration must be given in integer number of days (for day-partial) or minutes (for time-partial).

Pagination is NOT supported for time-based availability filtering, or when day-based filtering is used in combination with minDuration.

Pagination is not supported in the following cases:

time-full or time-partial queries
day-partial queries using minDuration

In those cases, the query returns up to 100 results (subject to the perPage query parameter), and use of page for accessing further results is not supported. In order to make sure you get the most relevant query results, adjust you query criteria and use sorting.

Sorting

The query results are ordered subject to the following rules:

When keywords parameter is used and sort parameter is not defined, listings are ordered by relevance score in descending order (i.e. most relevant listings first).
When origin parameter is used, listings are ordered by distance from the given origin location in ascending order.
Otherwise, listings are ordered according to the specification given with sort query parameter. The default value is createdAt, i.e. listings are ordered by createdAt time in descending order.

The sort query parameter takes the form of comma-separated list of up to 3 attributes. Results are ordered first by the first one, then by the second and third, if given. Sorting can be done by the following attributes:

Attribute	Description
createdAt	Sort by listing creation time.
price	Sort by listing's price amount (only considers the numeric value of the price, ignoring currency, i.e. no currency conversion is performed).
pub_*	Sort by a numeric `publicData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
meta_*	Sort by a numeric `metadata` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.

The order is descending for each attribute, but can be reversed by prefixing the attribute with a - sign.

Examples:

sort=-createdAt will return listings ordered by createdAt in ascending order
sort=meta_rating will return listings ordered by metadata rating in descending order
sort=pub_gears,-price will return listings ordered first by publicData gears in descending order and then by price amount in ascending order.

Pagination limits

When pagination is supported, this endpoint has a limit on the maximum number of pages that can be accessed when the total number of listings that match the query criteria exceeds 10,000. This is indicated in the API response by the presence of paginationLimit key with an integer value in the API response's meta. Use an additional filter to partition the result set and avoid the limitation. For example, a filter in createdAt time, using the createdAtStart and createdAtEnd query parameters, is well suited for this, as the createdAt value for listings is immutable. See Pagination for details.

Own listings

API prefix

/v1/api/own_listings/

Example resource

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 1
          },
          {
            "dayOfWeek": "tue",
            "seats": 0
          },
          {
            "dayOfWeek": "fri",
            "seats": 4
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 1
          },
          {
            dayOfWeek: "tue",
            seats: 0
          },
          {
            dayOfWeek: "fri",
            seats: 7
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

The ownListing API resource type represents information about a listing that is visible to its author. The ownListing resource attributes are a superset of the listing resource attributes.

All /own_listings/* API endpoints require an authenticated user access token.

`ownListing` resource format

Attribute	Description
title	(string) Listing's title.
description	(string) Listing's description.
geolocation	(object, location) Latitude (`lat`) and longitude (`lng`) of the listing's location.
createdAt	(string, timestamp) The date and time when the listing was created in ISO 8601 format.
price	(object, money) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object) Listing's availability plan. See `ownListing` availability plan.
publicData	(object) Listing's public data. See Extended data.
privateData	(object) Listing's private data. See Extended data.
metadata	(object) Listing's public metadata. See Extended data.
state	(string) The listing's current state. See `ownListing` states.
deleted	(boolean) Flag indicating whether the listing has been deleted. If `true`, all other attributes of the listing will be returned as default values (`false` for booleans and `null` for all else).

`ownListing` states

An ownListing resource type may be in one of the following states:

State	Description
draft	Listing is in draft state and has not been published yet. Listings that are in draft state are never returned by the public `/listings` API queries.
pendingApproval	Listing is pending operator approval. Newly created listings have this state, when the marketplace has the listing approval feature enabled. Listings that are pending approval are never returned by the public `/listings` API queries.
published	Listing is published and discoverable via the `/listings/query` API endpoint.
closed	A published listing can be closed by its author or a marketplace operator. Closed listings are not returned in search results or public listing queries and new transactions can not be initiated with them, but they can still be accessed as own listings or via the listing ID, or when related to another known resource (such as `transaction`). The intention of closing a listing is not to delete it, but to stop advertising it. A closed listing can be opened, which sets it in `published` state again.

`ownListing` availability plan

An availability plan can be specified to indicate in what days or times of a week a listing is available for booking. There are two types of availability plans: day-based and time-based. The day-based plan allows availability to be defined on day-level basis. With the time-based option the availability can be defined for different time ranges for each day of the week.

For more information on how availability management works, see Listing availability management.

Attribute	Description
type	(string) Availability plan type. Possible types are `availability-plan/day` for day-based availability and `availability-plan/time` for time-based availability.
timezone	(string) Only for the `availability-plan/time` type. Time zone in which the plan is set. Supports time zone names from the TZ time zone database, for example "Europe/Berlin". See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones.
entries	(array) List of zero or more availability entries for the plan.
entries.*.dayOfWeek	(string) An abbreviated day of week: `mon`, `tue`, `wed`, `thu`, `fri`, `sat` or `sun`.
entries.*.seats	(number) An integer number of available seats for the given day of week. The number of seats indicate how many times a given date can be booked. Setting `seats` to 0 means that the entry is unavailable for bookings.
entries.*.startTime	(string) Only for the `availability-plan/time` type. Start time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5.
entries.*.endTime	(string) Only for the `availability-plan/time` type. End time for the availability slot in hh:mm format so that the number of minutes is a multiple of 5. 00:00 can be used to express midnight.

If a day-based availability plan is set, but an entry is missing for a given day of the week, that day is interpreted to have 0 available seats, i.e. is unavailable for booking. As for time-based plans, only the specified time slots are considered to be available.

Listings without an availability plan are interpreted to have a day-based plan with 1 seat available for each day of the week. This is to ensure that the Marketplace API treats such listings the same way as it did prior to introducing availability management.

Passing null as an availability plan will make the listing default to daily availability plan with 1 seat. To make the listing unavailable, pass availability plan with 0 seats.

When computing availability information for a given concrete date, if an availability entry can not be resolved due to the start or end times being invalid, that entry is omitted from consideration for that date. One example of what might cause this is daylight saving time. Whenever appropriate, availability exceptions should be set for a listing to make up for the possible ommitted entries.

`ownListing` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the listing.
author	currentUser	one	The marketplace user, to whom the listing belongs. Note that the related resource is `currentUser`, rather than `user`. Supported nested relationships: `author.profileImage`.
images	image	many	(optional) The ordered list of listing images, if any. It is advisable to limit the number of returned images when including this relationship in response.
currentStock	stock	one	(optional) The listing's currently available stock, if set.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show own listing

HTTP request

GET /v1/api/own_listings/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/own_listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
sdk.ownListings.show({id: listingId}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 3
          },
          {
            "dayOfWeek": "fri",
            "seats": 1
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 3
          },
          {
            dayOfWeek: "fri",
            seats: 1
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Query returning data about one of the user's own listings by given ID. Returns error, if the listing does not belong to the current authenticated user.

Query parameters

Parameter	Description
id	The ID of the listing.

Query own listings

HTTP request

GET /v1/api/own_listings/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/own_listings/query' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.ownListings.query({}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "ownListing",
      "attributes": {
        "description": "7-speed Hybrid",
        "deleted": false,
        "geolocation": {
          "lat": 40.64542,
          "lng": -74.08508
        },
        "createdAt": "2018-03-23T08:40:24.443Z",
        "state": "published",
        "title": "Peugeot eT101",
        "availabilityPlan": null,
        "privateData": {
          "externalServiceId": "abcd-service-id-1234"
        },
        "publicData": {
          "address": {
            "city": "New York",
            "country": "USA",
            "state": "NY",
            "street": "230 Hamilton Ave"
          },
          "category": "road",
          "gears": 22,
          "rules": "This is a nice, bike! Please, be careful with it."
        },
        "metadata": {
          "promoted": true
        },
        "price": {
          "amount": 1590,
          "currency": "USD"
        }
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "ownListing",
      attributes: {
        description: "7-speed Hybrid",
        deleted: false,
        geolocation: LatLng {lat: 40.64542, lng: -74.08508},
        createdAt: new Date("2018-03-23T08:40:24.443Z"),
        state: "published",
        title: "Peugeot eT101",
        availabilityPlan: null,
        privateData: {
          externalServiceId: "abcd-service-id-1234"
        },
        publicData: {
          address: {
            city: "New York",
            country: "USA",
            state: "NY",
            street: "230 Hamilton Ave"
          },
          category: "road",
          gears: 22,
          rules: "This is a nice, bike! Please, be careful with it."
        },
        metadata: {
          promoted: true
        },
        price: Money {amount: 1590, currency: "USD"}
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all the authenticated user's own listings. Results are sorted by listing createdAt time in descending order (i.e. newest listings are returned first).

Query parameters

Parameter	Description
ids	(comma separated list of uuids, optional) List of uuids. Match only listings with an ID contained in the given list. A maximum of 100 IDs can be given.
states	(comma separated list of strings, optional) List of one or more states to filter the results by. Only listings in one of the given states are returned.
keywords	(string) Narrow down and sort search results based on given keywords. The keywords are matched against listing title, description and optionally also specific `publidData` fields with type `text` defined in the listing public data schema of a marketplace. Can not be combined with the `origin` parameter.
origin	Search listings, based on given location. The location is given as comma-separated tuple of latitude and longitude values (e.g. `40.12,-70.3345`). The listings in the query result are sorted by distance from the given origin. Can not be combined with the `keywords` parameter.
bounds	Match only listings within a bounding box. The bounding box is given as comma-separated list of four coordinate values: NE lat, NE, lng, SW lat and SW lng. E.g. `43.0,-73.0,40.0,-77.0`.
price	(integer or integer range) Match only listings with price amount within given range. The amounts must be given as integers in the currency's minor unit (e.g. cents for USD). The currency of the listing price has no effect on the query. See Price filtering below for range syntax.
start	(timestamp) Start time of the availability interval to match listings against in ISO 8601 format. The start time must be between one day in the past and 365 days in the future. If omitted, the listings' availability data is ignored in the query. See Availability filtering below.
end	(timestamp) End time of the availability interval to match listings against (exclusive) in ISO 8601 format. The end time must be after the `start` time and must be at most 365 days in the future or at most 90 days from the `start` time (whichever comes sooner). See Availability filtering below.
seats	(integer) The number of seats a listing must have available at minimum on the given interval to to match the search criteria. See Availability filtering below. Default value is `1`.
availability	(string) The type of availability search. Accepts values: `day-full`, `day-partial`, `time-full` or `time-partial`. Default value is: `day-full`. DEPRECATED values `full` and `partial` are equivalent to `day-full` and `day-partial`, respectively. See Availability filtering below.
minDuration	(integer) Match only listings with an availability interval of at least this duration within the query range specified by `start` and `end`. Only supported when `availability` is set to either `day-partial` and `time-partial`. For `day-partial` queries, the value of `minDuration` is in days. For `time-partial` queries, the value of `minDuration` is in minutes. Default value is `0`, i.e. any duration of availability matches.
stockMode	(string) The type of stock query. Control whether listing queries using `minStock` match listings without any defined stock. The value must be one of `strict` (the default) or `match-undefined`. If `strict`, only listings that have explicitly defined stock quantity will match. If `match-undefined`, the query will also match listings without any set stock.
minStock	(integer) Match only listings that have current stock quantity equal to or greater than the given integer number. If `stockMode` is set to `match-undefined`, the query will also match any listings without a defined stock quantity.
pub_*	Query listings by `publicData` attribute(s). See Extended data filtering below.
meta_*	Query listings by `metadata` attribute(s). See Extended data filtering below.
sort	(string) Specify sort criteria. Can not be used in combination with the `origin` query parameter. Default is `createdAt` See Sorting below.

Price filtering

price range can be specified as:

Query syntax	Description
`price=VALUE`	Match listings that have price amount exactly equal to `VALUE`.
`price=START,END`	Match listings that have price amount greater than or equal to `START` and less than `END`.
`price=START,`	Match listings that have price amount greater than or equal to `START`.
`price=,END`	Match listings that have price amount less than `END`.

Extended data filtering

Schema type	Schema cardinality	Query syntax	Description
enum	one	pub_`ATTRIBUTE_KEY`=`VALUE1,[VALUE2[,...]]`	Match listings that have any of the given values as the exact value of `ATTRIBUTE_KEY` (i.e. `OR` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`has_all:VALUE1[,VALUE2[,...]]`	Match listings that have all given values for the given multi-enum `ATTRIBUTE_KEY` (i.e. `AND` semantics).
enum	many	pub_`ATTRIBUTE_KEY`=`VALUE1[,VALUE2[,...]]`	Same as `has_all:`, we use `AND` semantics by default.
enum	many	pub_`ATTRIBUTE_KEY`=`has_any:VALUE1[,VALUE2[,...]]`	Match listings that have any of the given values for the multi-enum `ATTRIBUTE_KEY` (i.e. `OR` semantics).
long	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is exactly equal to `VALUE`.
long	one	pub_`ATTRIBUTE_KEY`=`START,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START` and less than `END`.
long	one	pub_`ATTRIBUTE_KEY`=`START,`	Match listings that have a value of `ATTRIBUTE_KEY` that is greater than or equal to `START`.
long	one	pub_`ATTRIBUTE_KEY`=`,END`	Match listings that have a value of `ATTRIBUTE_KEY` that is less than `END`.
boolean	one	pub_`ATTRIBUTE_KEY`=`VALUE`	Match listings that have a value of `ATTRIBUTE_KEY` that is equal to `VALUE`.
text	one	keywords=`KEYWORDS`	Match and sort listings that have a string from `KEYWORDS` in listing title, description or extended data attributes with type `text`.

Availability filtering

The availability filtering is controlled by the following query parameters: start, end, availability, seats and minDuration. The following rules apply:

When availability is set to either day-full or day-partial, only listings with a day-based availability plan are matched.
When availability is set to time-full or time-partial, only listings with time-based availability plans are matched.
day-full and time-full availability queries match only listings that have availability with the required number of seats for the entire duration of the query range (specified by start and end).
day-partial and time-partial availability queries match only listings that have some availability with the required number of seats and minDuration for the given query range (specified by start and end). minDuration must be given in integer number of days (for day-partial) or minutes (for time-partial).

Pagination is NOT supported for time-based availability filtering, or when day-based filtering is used in combination with minDuration.

Pagination is not supported in the following cases:

time-full or time-partial queries
day-partial queries using minDuration

Sorting

The query results are ordered subject to the following rules:

When keywords parameter is used and sort parameter is not defined, listings are ordered by relevance score in descending order (i.e. most relevant listings first).
When origin parameter is used, listings are ordered by distance from the given origin location in ascending order.
Otherwise, listings are ordered according to the specification given with sort query parameter. The default value is createdAt, i.e. listings are ordered by createdAt time in descending order.

Attribute	Description
createdAt	Sort by listing creation time.
price	Sort by listing's price amount (only considers the numeric value of the price, ignoring currency, i.e. no currency conversion is performed).
pub_*	Sort by a numeric `publicData` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.
meta_*	Sort by a numeric `metadata` top-level attribute. The attribute must have corresponding data schema defined of type `long`. Listings that do not have the given attribute defined are returned last, unless the schema defines a default value, in which case that value is used when sorting.

The order is descending for each attribute, but can be reversed by prefixing the attribute with a - sign.

Examples:

sort=-createdAt will return listings ordered by createdAt in ascending order
sort=meta_rating will return listings ordered by metadata rating in descending order
sort=pub_gears,-price will return listings ordered first by publicData gears in descending order and then by price amount in ascending order.

Pagination limits

When query parameters for filtering or non-default sorting is used, this endpoint has a limit on the maximum number of pages that can be accessed when the total number of listings that match the query criteria exceeds 10,000. This is indicated in the API response by the presence of paginationLimit key with an integer value in the API response's meta. Use an additional filter to partition the result set and avoid the limitation. For example, a filter in createdAt time, using the createdAtStart and createdAtEnd query parameters, is well suited for this, as the createdAt value for listings is immutable. See Pagination for details.

Create listing

HTTP request

POST /v1/api/own_listings/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/create?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "title": "Peugeot eT101",
  "description": "7-speed Hybrid",
  "geolocation": {
    "lat": 40.64542,
    "lng": -74.08508
  },
  "availabilityPlan": {
    "type": "availability-plan/day",
    "entries": [
      {
        "dayOfWeek": "mon",
        "seats": 3
      },
      {
        "dayOfWeek": "fri",
        "seats": 1
      }
    ]
  },
  "privateData": {
    "externalServiceId": "abcd-service-id-1234"
  },
  "publicData": {
    "address": {
      "city": "New York",
      "country": "USA",
      "state": "NY",
      "street": "230 Hamilton Ave"
    },
    "category": "road",
    "gears": 22,
    "rules": "This is a nice, bike! Please, be careful with it."
  },
  "price": {
    "amount": 1590,
    "currency": "USD"
  },
  "images": [
    "6a177221-247e-42a9-9cca-403238b86d7c",
    "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
  ]
}'

sdk.ownListings.create({
  title: "Peugeot eT101",
  description: "7-speed Hybrid",
  geolocation: new LatLng(40.64542, -74.08508),
  availabilityPlan: {
    type: "availability-plan/day",
    entries: [
      {
        dayOfWeek: "mon",
        seats: 3
      },
      {
        dayOfWeek: "fri",
        seats: 1
      }
    ]
  },
  privateData: {
    externalServiceId: "abcd-service-id-1234"
  },
  publicData: {
    address: {
      city: "New York",
      country: "USA",
      state: "NY",
      street: "230 Hamilton Ave"
    },
    category: "road",
    gears: 22,
    rules: "This is a nice, bike! Please, be careful with it."
  },
  price: new Money(1590, "USD"),
  images: [
    new UUID("6a177221-247e-42a9-9cca-403238b86d7c"),
    new UUID("f8afadaa-dd4f-4536-b9a7-b405834dc25d")
  ]
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": {
        "type": "availability-plan/day",
        "entries": [
          {
            "dayOfWeek": "mon",
            "seats": 3
          },
          {
            "dayOfWeek": "fri",
            "seats": 1
          }
        ]
      },
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {},
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "6a177221-247e-42a9-9cca-403238b86d7c", "type": "image"},
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      "id": "6a177221-247e-42a9-9cca-403238b86d7c",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 3
          },
          {
            dayOfWeek: "fri",
            seats: 1
          }
        ]
      },
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {},
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"}, type: "image"},
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

Command that creates a new listing. The new listing's state is published, unless the marketplace is configured to require listing approvals, in which case the state is pendingApproval. See ownListing states for details.

Responds with a forbidden error (403), if the user has the permission to publish listings effectively denied. Otherwise, any authenticated marketplace user can create new listings.

Body parameters

Parameter	Description
title	(string) Listing's title. Must be between 1 and 1000 characters.
description	(string, optional) Listing's description. Must be between 1 and 5000 characters.
geolocation	(object, optional) Latitude (`lat`) and longitude (`lng`) of the listing's location.
price	(object, optional) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object, optional) Listing's availability plan. See `ownListing` availability plan for the object format.
privateData	(object, optional) Listing's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB.
publicData	(object, optional) Listing's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB.
images	(array, optional) List of image IDs for the listing. The images will be set in the given order. The images must not already be used by other listings. See also `/images/upload`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Create draft listing

HTTP request

POST /v1/api/own_listings/create_draft

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/create_draft?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "title": "Peugeot eT101",
  "description": "7-speed Hybrid",
  "geolocation": {
    "lat": 40.64542,
    "lng": -74.08508
  },
  "privateData": {
    "externalServiceId": "abcd-service-id-1234"
  },
  "publicData": {
    "address": {
      "city": "New York",
      "country": "USA",
      "state": "NY",
      "street": "230 Hamilton Ave"
    },
    "category": "road",
    "gears": 22,
    "rules": "This is a nice, bike! Please, be careful with it."
  },
  "price": {
    "amount": 1590,
    "currency": "USD"
  },
  "images": [
    "6a177221-247e-42a9-9cca-403238b86d7c",
    "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
  ]
}'

sdk.ownListings.createDraft({
  title: "Peugeot eT101",
  description: "7-speed Hybrid",
  geolocation: new LatLng(40.64542, -74.08508),
  privateData: {
    externalServiceId: "abcd-service-id-1234"
  },
  publicData: {
    address: {
      city: "New York",
      country: "USA",
      state: "NY",
      street: "230 Hamilton Ave"
    },
    category: "road",
    gears: 22,
    rules: "This is a nice, bike! Please, be careful with it."
  },
  price: new Money(1590, "USD"),
  images: [
    new UUID("6a177221-247e-42a9-9cca-403238b86d7c"),
    new UUID("f8afadaa-dd4f-4536-b9a7-b405834dc25d")
  ]
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "draft",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {},
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "6a177221-247e-42a9-9cca-403238b86d7c", "type": "image"},
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      "id": "6a177221-247e-42a9-9cca-403238b86d7c",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "draft",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {},
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"}, type: "image"},
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

Command that creates a new listing in draft state. See ownListing states for details.

Responds with a forbidden error (403), if the user has the permission to publish listings effectively denied. Otherwise, any authenticated marketplace user can create new draft listings.

Body parameters

Parameter	Description
title	(string) Listing's title. Must be between 1 and 1000 characters.
description	(string, optional) Listing's description. Must be between 1 and 5000 characters.
geolocation	(object, optional) Latitude (`lat`) and longitude (`lng`) of the listing's location.
price	(object, optional) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD).
availabilityPlan	(object, optional) Listing's availability plan. See `ownListing` availability plan for the object format.
privateData	(object, optional) Listing's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB.
publicData	(object, optional) Listing's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB.
images	(array, optional) List of image IDs for the listing. The images will be set in the given order. The images must not already be used by other listings. See also `/images/upload`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Update listing

HTTP request

POST /v1/api/own_listings/update

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/update?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "description": "Brand new track bike.",
  "privateData": {
    "externalServiceId": "new-service-id-4324"
  },
  "publicData": {
    "address": {"country": "USA"}
    "category": "track",
    "rules": null
  },
  "images": [
    "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
  ]
}'

sdk.ownListings.update({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  description: "Brand new track bike.",
  privateData: {
    externalServiceId: "new-service-id-4324"
  },
  publicData: {
    address: {
      country: "USA"
    }
    category: "track",
    rules: null
  },
  images: [
    new UUID("f8afadaa-dd4f-4536-b9a7-b405834dc25d")
  ]
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "Brand new track bike.",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "new-service-id-4324"
      },
      "publicData": {
        "address": {
          "country": "USA"
        },
        "category": "track",
        "gears": 22
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "Brand new track bike.",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "new-service-id-4324"
      },
      publicData: {
        address: {
          country: "USA"
        },
        category: "track",
        gears: 22
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    }
  ]
}

Command for updating listing details. Cannot be used to change listing state.

Body parameters

Parameter	Description
id	(uuid) The ID of the listing that is being updated.
title	(string, optional) Listing's title. Must be between 1 and 1000 characters.
description	(string, optional) Listing's description. Must be between 1 and 5000 characters.
geolocation	(object, optional) Latitude (`lat`) and longitude (`lng`) of the listing's location. Pass `null` to remove the location data from the listing.
price	(object, optional) Listing's price. `currency` is the currency code and `amount` is integer representing amount in the currency's minor unit (e.g. cents for USD). Pass `null` to remove the price from the listing.
availabilityPlan	(object, optional) Listing's availability plan. See `ownListing` availability plan for the object format. The availability plan must be specified in full, partial updates are not supported. Passing `null` will make the listing default to daily availability plan with 1 seat. To make the listing unavailable, pass availability plan with 0 seats.
publicData	(object, optional) Listing's public data. See Extended data. The total size of the public data object as JSON string must not exceed 50KB. The given `publicData` object is merged with the existing listing `publicData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the listing's `publicData`.
privateData	(object, optional) Listing's private data. See Extended data. The total size of the private data object as JSON string must not exceed 50KB. The given `privateData` object is merged with the existing listing `privateData` on the top level (i.e. non-deep merge). Nested values are set as given. Top-level keys that have value `null` are removed from the listing's `privateData`.
images	(array, optional) List of image IDs for the listing. The listing's images will be set to the exact given list, i.e. new images are added to the listing, listing images that are not given are deleted and order is set as given. See also `/images/upload`.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Publish draft listing

HTTP request

POST /v1/api/own_listings/publish_draft

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/publish_draft?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

sdk.ownListings.publishDraft({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for publishing a draft listing. The listing's state is set to published or pendingApproval, depending on whether the marketplace is configured to require listing approvals. If listing approval is not required, the published listing will become discoverable via the /listings/query API endpoint.

Responds with a forbidden error (403), if the user has the permission to publish listing effectively denied.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Discard draft listing

HTTP request

POST /v1/api/own_listings/discard_draft

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/discard_draft' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

sdk.ownListings.discardDraft({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: false
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing"
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing"
  }
}

Command for permanently discarding a draft listing. The listing is removed and cannot be accessed again.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

Close listing

HTTP request

POST /v1/api/own_listings/close

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/close?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

sdk.ownListings.close({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "closed",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "closed",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for closing a listing. The listing's state is be set to closed. When a listing is closed, it is not anymore discoverable via the /listings/query API endpoint, but can be found by ID or through other related resources (e.g. transaction). See Concepts for details.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Open listing

HTTP request

POST /v1/api/own_listings/open

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/open?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}'

sdk.ownListings.open({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f")
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    }
  }
}

Command for opening a closed listing. The listing's state is set to published.

Responds with a forbidden error (403), if the user has the permission to publish listing effectively denied.

Body parameters

Parameter	Description
id	(uuid) The listing ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Add image to listing

HTTP request

POST /v1/api/own_listings/add_image

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/own_listings/add_image?expand=true,include=images' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "imageId": "5a8f34f6-202c-4916-af7a-53d56004e872"
}'

sdk.ownListings.addImage({
  id: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  listingId: new UUID("5a8f34f6-202c-4916-af7a-53d56004e872")
}, {
  expand: true,
  include: ["images"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "ownListing",
    "attributes": {
      "description": "7-speed Hybrid",
      "deleted": false,
      "geolocation": {
        "lat": 40.64542,
        "lng": -74.08508
      },
      "createdAt": "2018-03-23T08:40:24.443Z",
      "state": "published",
      "title": "Peugeot eT101",
      "availabilityPlan": null,
      "privateData": {
        "externalServiceId": "abcd-service-id-1234"
      },
      "publicData": {
        "address": {
          "city": "New York",
          "country": "USA",
          "state": "NY",
          "street": "230 Hamilton Ave"
        },
        "category": "road",
        "gears": 22,
        "rules": "This is a nice, bike! Please, be careful with it."
      },
      "metadata": {
        "promoted": true
      },
      "price": {
        "amount": 1590,
        "currency": "USD"
      }
    },
    "relationships": {
      "images": {
        "data": [
          {"id": "6a177221-247e-42a9-9cca-403238b86d7c", "type": "image"},
          {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"},
          {"id": "5a8f34f6-202c-4916-af7a-53d56004e872", "type": "image"}
        ]
      }
    }
  },
  "included": [
    {
      "id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/5a8f34f6-202c-4916-af7a-53d56004e872"
          }
        }
      }
    },
    {
      "id": "6a177221-247e-42a9-9cca-403238b86d7c",
      "type": "image",
      "attributes": {
        "variants": {
          "default": {
            "width": 720,
            "height": 540,
            "url": "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "ownListing",
    attributes: {
      description: "7-speed Hybrid",
      deleted: false,
      geolocation: LatLng {lat: 40.64542, lng: -74.08508},
      createdAt: new Date("2018-03-23T08:40:24.443Z"),
      state: "published",
      title: "Peugeot eT101",
      availabilityPlan: null,
      privateData: {
        externalServiceId: "abcd-service-id-1234"
      },
      publicData: {
        address: {
          city: "New York",
          country: "USA",
          state: "NY",
          street: "230 Hamilton Ave"
        },
        category: "road",
        gears: 22,
        rules: "This is a nice, bike! Please, be careful with it."
      },
      metadata: {
        promoted: true
      },
      price: Money {amount: 1590, currency: "USD"}
    },
    relationships: {
      images: {
        data: [
          {id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"}, type: "image"},
          {id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"}, type: "image"},
          {id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"}, type: "image"}
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "f8afadaa-dd4f-4536-b9a7-b405834dc25d"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/f8afadaa-dd4f-4536-b9a7-b405834dc25d"
          }
        }
      }
    },
    {
      id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/5a8f34f6-202c-4916-af7a-53d56004e872"
          }
        }
      }
    },
    {
      id: UUID {uuid: "6a177221-247e-42a9-9cca-403238b86d7c"},
      type: "image",
      attributes: {
        variants: {
          default: {
            width: 720,
            height: 540,
            url: "https://www.example.com/image/6a177221-247e-42a9-9cca-403238b86d7c"
          }
        }
      }
    }
  ]
}

Command for adding a new image to the list of listing images. The image is appended to the end of the list.

Body parameters

Parameter	Description
id	(uuid) The listing ID.
imageId	(uuid) The image ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Availability exceptions

API prefix

/v1/api/availability_exceptions/

Example resource

{
  "data": {
    "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
    "type": "availabilityException",
    "attributes": {
      "seats": 1,
      "start": "2018-11-26T00:00:00.000Z",
      "end": "2018-11-28T00:00:00.000Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException",
    attributes: {
      seats: 1,
      start: new Date("2018-11-26T00:00:00.000Z"),
      end: new Date("2018-11-28T00:00:00.000Z")
    }
  }
}

The availabilityException API resource type represents information about a single availability exception. Availability exceptions are always linked to a particular listing and serve to override the listing's availability plan for a given time range. See also Listing availability management.

All /availability_exceptions/* API endpoints require an authenticated user access token.

`availabilityException` resource format

Attribute	Description
seats	(number) An integer number of available seats for the exception. Setting `seats` to 0 means that the listing is unavailable.
start	(string, timestamp) The date and time when the availability exception starts. Specified in ISO 8601 format.
end	(string, timestamp) The date and time (exclusive) when the availability exception ends. Specified in ISO 8601 format.

`availabilityException` relationships

Relationship	Resource type	Cardinality	Description
ownListing	ownListing	one	The listing to which the availability exception applies.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query availability exceptions

HTTP request

GET /v1/api/availability_exceptions/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/availability_exceptions/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2018-11-27T00:00:00.000Z&end=2018-12-30T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.availabilityExceptions.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-11-27T00:00:00.000Z"),
  end: new Date("2018-12-30T00:00:00.000Z")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
      "type": "availabilityException",
      "attributes": {
        "seats": 1,
        "start": "2018-11-26T00:00:00.000Z",
        "end": "2018-11-28T00:00:00.000Z"
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
      type: "availabilityException",
      attributes: {
        seats: 1,
        start: new Date("2018-11-26T00:00:00.000Z"),
        end: new Date("2018-11-28T00:00:00.000Z")
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all the availability exceptions for a given listing and time range.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) The start date and time for the query range in ISO 8601 format. The start time must be between 366 days in the past and 366 days in the future.
end	(timestamp) The end date and time for the query range in ISO 8601 format. The end time must be after the `start` time and must be at most 366 days in the future and at most 90 days after the `start` time.

Create availability exceptions

HTTP request

POST /v1/api/availability_exceptions/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/availability_exceptions/create?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "start": "2018-11-26T00:00:00.000Z",
  "end": "2018-11-28T00:00:00.000Z",
  "seats": 1
}'

sdk.availabilityExceptions.create({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-11-26T00:00:00.000Z"),
  end: new Date("2018-11-28T00:00:00.000Z"),
  seats: 3
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response shell { "data": { "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e", "type": "availabilityException", "attributes": { "seats": 3, "start": "2018-11-26T00:00:00.000Z", "end": "2018-11-28T00:00:00.000Z" } } }

// res.data
{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException",
    attributes: {
      seats: 3,
      start: new Date("2018-11-26T00:00:00.000Z"),
      end: new Date("2018-11-28T00:00:00.000Z")
    }
  }
}

Create a new availability exception for a given listing. You can not create availability exceptions with overlapping time ranges.

Body parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
seats	(number) Integer number of available seats.
start	(string, timestamp) The date and time when the availability exception starts. Specified in ISO 8601 format. The availability exception start time must be at most 365 days in the future.
end	(string, timestamp) The date and time (exclusive) when the availability exception ends. Specified in ISO 8601 format. The availability exception end time must be at most 365 days in the future.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Both start and end time minutes must be multiple of 5 and seconds and milliseconds must be 0. For example:

valid: 2018-11-26T02:00:00.000Z
invalid: 2018-11-26T00:02:30.000Z

Delete availability exceptions

HTTP request

POST /v1/api/availability_exceptions/delete

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/availability_exceptions/delete' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e"
}'

sdk.availabilityExceptions.delete({
  id: new UUID("34cf5423-04ee-42c7-8786-2e206ef34a9e")
}, {
  expand: false
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "34cf5423-04ee-42c7-8786-2e206ef34a9e",
    "type": "availabilityException"
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "34cf5423-04ee-42c7-8786-2e206ef34a9e"},
    type: "availabilityException"
  }
}

Command for deleting an availability exception with a given ID.

Body parameters

Parameter	Description
id	(uuid) The availability exception ID.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Images

API prefix

/v1/api/images

Example resource

{
  "data": {
    "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "name": "default",
          "width": 720,
          "height": 540,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          "name": "landscape-crop",
          "width": 800,
          "height": 600,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          "name": "landscape-crop2x",
          "width": 1600,
          "height": 1200,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
    type: "image",
    attributes: {
      variants: {
        default: {
          name: "default",
          width: 720,
          height: 540,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        },
        "landscape-crop": {
          name: "landscape-crop",
          width: 800,
          height: 600,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop"
        },
        "landscape-crop2x": {
          name: "landscape-crop2x",
          width: 1600,
          height: 1200,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872?v=landscape-crop2x"
        }
      }
    }
  }
}

The image resource represents user profile and listing images. Images can only be uploaded as JPG, PNG, or non-animated GIF.

All /images/* API endpoints require an authenticated user access token.

`image` resource format

Attribute	Description
variants	(object) Object containing image variant information. Keys are variant names and values are objects representing the variant.
variants.*.width	(number) The actual width of the image in pixels after the transformation corresponding to the variant.
variants.*.height	(number) The actual height of the image in pixels after the transformation corresponding to the variant.
variants.*.url	(string) The public URL for the image variant. Always use the returned URL exactly as returned by the API. Do not attempt to manually construct an image URL.
variants.*.name	(string) The variant name. Same as the key.

Image variants

An example request that fetches a listing with two image variants: a predefined one and a custom one that is defined in the request.

$ curl 'https://flex-api.sharetribe.com/v1/api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&include=images&fields.image=variants.square-small,variants.my-variant&imageVariant.my-variant=w:320;h:640;fit:scale' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

const sdkUtil = sharetribeSdk.util;
var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");

sdk.listings.show({
  id: listingId,
  include: ["images"],
  "fields.image": ["variants.square-small", "variants.my-variant"],
  "imageVariant.my-variant": sdkUtil.objectQueryString({
    w: 320,
    h: 640,
    fit: 'scale'
  })
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "type": "listing",
    "attributes": {...},
    "relationships": {
      "images": {
        "data": [
          {
            "id": "4617c584-edfd-49e9-be43-2f1d50fb6e35",
            "type": "image"
          }
        ]
      }
    }
  },
  "included": [
    {
      "id": "4617c584-edfd-49e9-be43-2f1d50fb6e35",
      "type": "image",
      "attributes": {
        "variants": {
          "my-variant": {
            "height": 640,
            "width": 320,
            "url": "https://www.example.com/image/5f2a6d44-c826-4a20-aae8-4c24b80b8dc6",
            "name": "my-variant"
          },
          "square-small": {
            "height": 240,
            "width": 240,
            "url": "https://www.example.com/image/5f2a6d65-28fe-49c5-9218-8c6a3924349a",
            "name": "square-small"
          }
        }
      }
    }
  ]
}

{
  data: {
    id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
    type: "listing",
    attributes: {...},
    relationships: {
      images: {
        data: [
          {
            id: UUID {uuid: "4617c584-edfd-49e9-be43-2f1d50fb6e35"},
            type: "image"
          }
        ]
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "4617c584-edfd-49e9-be43-2f1d50fb6e35"},
      type: "image",
      attributes: {
        variants: {
          "my-variant": {
            height: 640,
            width: 320,
            url: "https://www.example.com/image/5f2a6d44-c826-4a20-aae8-4c24b80b8dc6",
            name: "my-variant"
          },
          "square-small": {
            height: 240,
            width: 240,
            url: "https://www.example.com/image/5f2a6d65-28fe-49c5-9218-8c6a3924349a",
            name: "square-small"
          }
        }
      }
    }
  ]
}

Unlike other resource attributes, variants other than default need to be explicitly requested via Sparse attributes query.

Predefined image variants

The following image variants are available for profile and listing images:

Variant	Fit mode	Width	Height
default	scale	750px	750px
landscape-crop	crop	400px	267px
landscape-crop2x	crop	800px	533px
landscape-crop4x	crop	1600px	1066px
landscape-crop6x	crop	2400px	1602px
scaled-small	scale	320px	320px
scaled-medium	scale	750px	750px
scaled-large	scale	1024px	1024px
scaled-xlarge	scale	2400px	2400px
square-small	crop	240px	240px
square-small2x	crop	480px	480px
facebook	crop	1200px	630px
twitter	crop	600px	314px

Custom image variants

To request a custom image variant, a sparse attribute definition needs to be accompanied with a corresponding image variant definition. The definition is passed in a imageVariant.[VARIANT NAME] query parameter: ?fields.image=variants.my-variant&imageVariant.my-variant=w:320;h:640;fit:scale.

The imageVariant.* parameter contains semicolon-separated key:value pairs describing the image variant. The following keys and values are supported:

Parameter	Description
w	(integer) Image width. Value must be between 8 and 3072. `w` or `h` can be omitted when fit is `scale`.
h	(integer) Image height. Value must be between 8 and 3072. `w` or `h` can be omitted when fit is `scale`.
fit	(string) Fit mode for resizing the original image. Accepts values `scale` and `crop`. See descriptions of different fit modes below.

The amount of custom variants that can be requested with a single request is limited to 10.

Variant fit modes

Fit mode	Description
scale	Resizes the image to fit within the width and height dimensions preserving the image aspect ratio without cropping. The actual image smaller side will vary depending on the image aspect ratio. If image width or height is omitted image will be scaled using the provided dimension while maintaining aspect ratio.
crop	Resizes the image to fit both dimensions and crops away the excess. Uses edge detection algorithm for determining which portion of the image to center the crop on.

Upload image

HTTP request

POST /v1/api/images/upload

Example request

# Upload portrait.jpg local file
$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/images/upload' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -F "image=@portrait.jpg"

// file is e.g. the value of an HTML <input type="file" ...> element.
var file = document.getElementById('myFile').files[0];
sdk.images.upload({
  image: file
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "5a8f34f6-202c-4916-af7a-53d56004e872",
    "type": "image",
    "attributes": {
      "variants": {
        "default": {
          "width": 720,
          "height": 540,
          "url": "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        }
      }
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "5a8f34f6-202c-4916-af7a-53d56004e872"},
    type: "image",
    attributes: {
      variants: {
        default: {
          width: 720,
          height: 540,
          url: "https://www.example.com/images/5a8f34f6-202c-4916-af7a-53d56004e872"
        }
      }
    }
  }
}

Command for uploading a new image. The returned image can subsequently be used as a user profile image or a listing image.

The maximum allowed file size is 20MB.

Multipart body parameters

Note that this API endpoint requires that the body be sent as multipart/form-data

Parameter	Description
image	The image content.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
400	image-invalid-content	The uploaded image is in an unsupported format.
413	request-upload-over-limit	The uploaded file is too large.

Transactions

API prefix

/v1/api/transactions

Example resource

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {
        "phoneNumber": "+1-202-555-5555"
      },
      "metadata": {
        "refId": 1234
      },
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {
        phoneNumber: "+1-202-555-5555"
      },
      metadata: {
        refId: 1234
      },
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

The transaction API resource type represents information about transactions.

All /transactions/* API endpoints require an authenticated user access token.

`transaction` resource format

Attribute	Description
createdAt	(string) The date and time when the transaction was initiated in ISO 8601 format.
processName	(string) The (unique) name for the process this transaction uses
processVersion	(number) The version of the transaction process
lastTransition	(string) The name of the last transition that happened in the transaction. See Transaction process.
lastTransitionedAt	(string, timestamp) The date and time when the last transition in the transaction occurred, in ISO 8601 format.
lineItems	(array) Array of line item objects, that represent the pricing breakdown of the transaction.
lineItems.*.code	(string) The line item code. See the table below for list of possible codes.
lineItems.*.unitPrice	(object, money) Unit price.
lineItems.*.quantity	(number, optional) When applicable, the complete number of booked units that the line item represents. When `units` and `seats` are provided `quantity` always equals to `units x seats`. Can be non-integer or negative number.
lineItems.*.units	(number, optional) When applicable, the number of units that the line item represents. Multiplying `units` with `seats` equals `quantity`. Can be non-integer or negative number.
lineItems.*.seats	(number, optional) When applicable, the number of seats that the line item represents. Multiplying `seats` with `units` equals `quantity`. Must be a positive integer.
lineItems.*.percentage	(number, optional) When applicable, the percentage value that the line item represents. Can be negative. E.g. `5.0` (5%).
lineItems.*.lineTotal	(object, money) The line item total value. `amount` can be negative. The line total is always equal to either `quantity x unitPrice` or `percentage x unitPrice / 100`.
lineItems.*.reversal	(boolean) Flag indicating whether the line item is a reversal of another line item. Reversal are added when there has been a reversal (typically a refund).
lineItems.*.includedFor	(array) Array of strings, indicating whether the line item applies to `customer`, `provider` or both. For instance, a commission that the provider pays does not affect the total from the point of view of the customer.
payinTotal	(object, money) The total monetary amount of the payin (i.e. the amount paid by the customer). This amount is the sum total of all line items that apply to the customer (i.e. have `customer` in their `includedFor` lists).
payoutTotal	(object, money) The total monetary amount of the payout (i.e. the amoun paid to the provider). This amount is the sum total of all line items that apply to the provider (i.e. have `provider` in their `includedFor` lists).
protectedData	(object) Transaction's protected data. See Extended data for details.
metadata	(object) Transaction's metadata. See Extended data for details.
transitions	(array) The transaction's transition history - list of transition objects, in chronological order.
transitions.*.transition	(string) The name of the transition. See Transaction process.
transitions.*.createdAt	(string, timestamp) The date and time when the transition occurred in ISO 8601 format.
transitions.*.by	(string) The actor that performed the transition. One of `customer`, `provider`, `operator` or `system`.

The following table lists all currently available codes. Depending on your transaction process, the codes that your marketplace uses is a subset of the ones listed below.

Line item code	Description
line-item/day	Line item representing the price of daily booking for given number of days.
line-item/night	Line item representing the price of nightly booking for given number of nights.
line-item/units	Line item representing the price of units for given quantity.
line-item/units1	Line item representing the price of units type "1" for given quantity in a two unit transaction.
line-item/units2	Line item representing the price of units type "2" for given quantity in a two unit transaction.
line-item/negotiation	Line item representing negotiated change to the total price.
line-item/provider-commission	Line item representing commission that is paid by the provider.
line-item/customer-commission	Line item representing commission that is paid by the customer.
line-item/provider-fixed-commission	Line item representing a fixed commission that is paid by the provider.
line-item/customer-fixed-commission	Line item representing a fixed commission that is paid by the customer.
line-item/<custom code>	With custom pricing the line item code can be any string with `line-item/` prefix and a maximum length of 64 characters.

`transaction` relationships

Relationship	Resource type	Cardinality	Description
marketplace	marketplace	one	The marketplace of the transaction.
listing	listing	one	The listing that the transaction is about. Supported nested relationships: `listing.images`, `listing.currentStock`.
provider	user	one	The user who is author of the listing that the transaction is about. Supported nested relationships: `provider.profileImage`.
customer	user	one	The customer who initiated the transaction. Supported nested relationships: `customer.profileImage`.
booking	booking	one	(optional) The booking created by the transaction, if any.
stockReservation	stockReservation	one	(optional) The stock reservation created by the transaction, if any.
reviews	review	many	(optional) The reviews of the parties in the transaction, if any. Supported nested relationships: `reviews.author`, `reviews.author.profileImage`, `reviews.subject`, `reviews.subject.profileImage`.
messages	message	many	(optional) The messages that the parties have sent to one another as part of the transaction, if any. Note that there may be large number of messages. It is therefore recommended to use limits when including this relationship. Alternatively, use `/messages/query` API endpoint. Supported nested relationships: `messages.sender`, `messages.sender.profileImage`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show transaction

HTTP request

GET /v1/api/transactions/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/transactions/show?id=ef98e897-5b81-49a5-aca6-01d9759df075' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.transactions.show({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          unit: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

Query returning data about given transaction.

Query parameters

Parameter	Description
id	The ID of the transaction.

Query transactions

HTTP request

GET /v1/api/transactions/query

Example request

# Query transactions where the user is provider and the last transition is 'transition/request'
$ curl 'https://flex-api.sharetribe.com/v1/api/transactions/query?only=sale&lastTransitions=transition/request' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Query transactions where the user is provider and the last transition is 'transition/request'
sdk.transactions.query({
  only: "sale",
  lastTransitions: ["transition/request"]
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
      "type": "transaction",
      "attributes": {
        "createdAt": "2018-03-27T12:30:02.000Z",
        "processName": "preauth-with-nightly-booking",
        "processVersion": 3,
        "lastTransition": "transition/request",
        "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
        "payinTotal": {
          "amount": 6360,
          "currency": "USD"
        },
        "payoutTotal": {
          "amount": 5724,
          "currency": "USD"
        },
        "lineItems": [
          {
            "code": "line-item/day",
            "quantity": 4,
            "units": 2,
            "seats": 2,
            "reversal": false,
            "unitPrice": {
              "amount": 1590,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": 6360,
              "currency": "USD"
            },
            "includeFor": [
              "customer",
              "provider"
            ]
          },
          {
            "code": "line-item/provider-commission",
            "percentage": -10.0,
            "reversal": false,
            "unitPrice": {
              "amount": 6360,
              "currency": "USD"
            },
            "lineTotal": {
              "amount": -636,
              "currency": "USD"
            },
            "includeFor": [
              "provider"
            ]
          }
        ],
        "protectedData": {},
        "transitions": [
          {
            "transition": "transition/request",
            "createdAt": "2018-03-27T12:30:03.100Z",
            "by": "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
      type: "transaction",
      attributes: {
        createdAt: new Date("2018-03-27T12:30:02.000Z"),
        processName: "preauth-with-nightly-booking",
        processVersion: 3,
        lastTransition: "transition/request",
        lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
        payinTotal: {
          amount: 6360,
          currency: "USD"
        },
        payoutTotal: {
          amount: 5724,
          currency: "USD"
        },
        lineItems: [
          {
            code: "line-item/day",
            quantity: 4,
            units: 2,
            seats: 2,
            reversal: false,
            unitPrice: {
              amount: 1590,
              currency: "USD"
            },
            lineTotal: {
              amount: 6360,
              currency: "USD"
            },
            includeFor: [
              "customer",
              "provider"
            ]
          },
          {
            code: "line-item/provider-commission",
            percentage: -10.0,
            reversal: false,
            unitPrice: {
              amount: 6360,
              currency: "USD"
            },
            lineTotal: {
              amount: -636,
              currency: "USD"
            },
            includeFor: [
              "provider"
            ]
          }
        ],
        protectedData: {},
        transitions: [
          {
            transition: "transition/request",
            createdAt: new Date("2018-03-27T12:30:03.100Z"),
            by: "customer"
          }
        ]
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query the transactions in which the currently authenticated user participates. Results are sorted by transaction's createdAt time in descending order (i.e. most recent transactions are returned first).

Query parameters

Parameter	Description
createdAtStart	(timestamp, optional) Filter transactions by `createdAt` time. Only transactions created on or after the given time are returned. The timestamp must be in ISO 8601 format.
createdAtEnd	(timestamp, optional) Filter transactions by `createdAt` time. Only transactions created before the given time are returned. The timestamp must be in ISO 8601 format.
only	(string, optional) Query only sale or order transactions. One of `sale` or `order`. `sale` means that the authenticated user is the provider in the transaction and `order` means that the user is customer in the transaction.
userId	(uuid, optional) Return only transactions where the user with the given ID is either a customer or provider. Combine with `only` to specify that the given user must be specifically the customer (`only: sale`) or the provider (`only: order`) in all the matching transactions, i.e. the counterparty of the authenticated user.
listingId	(uuid, optional) Return only transactions for the given listing.
lastTransitions	(comma separated list of strings) List of transitions to filter the results by. Only transactions which have one of the given transitions as their `lastTransition` are returned.
processNames	(comma separated list of strings) List of transaction process names to filter the results by. Only transactions which have one of the given process names as their `processName` are returned.

Initiate transaction

HTTP request

POST /v1/api/transactions/initiate

Example request

# Example initiation assiming a process with daily booking
# and preauthorization.
$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/transactions/initiate' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "processAlias": "preauth-with-nightly-booking/release-1",
  "transition": "transition/request",
  "params": {
    "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "bookingStart": "2018-04-20T00:00:00.000Z",
    "bookingEnd": "2018-04-22T00:00:00.000Z",
    "seats": 2,
    "cardToken": "tok_mastercard"
  }
}'

// Example initiation assiming a process with daily booking
// and preauthorization.
sdk.transactions.initiate({
  processAlias: "preauth-with-nightly-booking/release-1",
  transition: "transition/request",
  params: {
    listingId: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    bookingStart: new Date("2018-04-20T00:00:00.000Z"),
    bookingEnd: new Date("2018-04-22T00:00:00.000Z"),
    seats: 2,
    cardToken: "tok_mastercard"
  }
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

Command that initiates a new transaction.

Body parameters

Parameter	Description
processAlias	(string) The process version alias for the transaction process that should be used for the transaction. If your marketplace uses the default transaction process, the default available alias is `preauth-with-nightly-booking/release-1`.
transition	(string) The name of one of your transaction process' possible initial transitions.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
402	transaction-payment-failed	Payment information was invalid or the payment was rejected by Stripe. Additional information can be found in the error `meta.stripeMessage`, `meta.stripeCode` and `meta.stripeDeclineCode`. See also Stripe errors documentation.
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible initial transitions.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-listing-not-found	The given listing can not be found.
400	transaction-booking-end-is-in-the-past	The given booking end time is in the past.
400	transaction-booking-start-before-end	The booking start time must be before the booking end time.
409	transaction-invalid-action-sequence	The given transition cannot be used to initialize a new transaction because the action sequence is invalid and some action precondition is not met.
409	transaction-unknown-alias	The given processAlias cannot be resolved to a process name and version

Speculatively initiate transaction

HTTP request

POST /v1/api/transactions/initiate_speculative

Example request

# Example speculative initiation assiming a process with daily booking
# and preauthorization.
$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/transactions/initiate_speculative?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "transition": "transition/request",
  "params": {
    "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    "bookingStart": "2018-04-20T00:00:00.000Z",
    "bookingEnd": "2018-04-22T00:00:00.000Z",
    "seats": 2,
    "cardToken": "tok_mastercard"
  }
}'

// Example speculative initiation assiming a process with daily booking
// and preauthorization.
sdk.transactions.initiateSpeculative({
  transition: "transition/request",
  params: {
    listingId: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
    bookingStart: new Date("2018-04-20T00:00:00.000Z"),
    bookingEnd: new Date("2018-04-22T00:00:00.000Z"),
    seats: 2,
    cardToken: "tok_mastercard"
  }
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/request",
      "lastTransitionedAt": "2018-03-27T12:30:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/request",
      lastTransitionedAt: new Date("2018-03-27T12:30:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        }
      ]
    }
  }
}

Command that simulates initiation of transaction with given parameters. No actual transaction is created, but this command can be used to validate the parameters or to get transaction price breakdown (via lineItems), as if a real transaction were initiated.

Body parameters

The parameters for this command are exactly the same as for the /transactions/initiate command.

Parameter	Description
processAlias	(string) The process version alias for the transaction process that should be used for the transaction. If your marketplace uses the default transaction process, the default available alias is `preauth-with-nightly-booking/release-1`.
transition	(string) The name of one of your transaction process' possible initial transitions.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible initial transitions.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-listing-not-found	The given listing can not be found.
400	transaction-booking-end-is-in-the-past	The given booking end time is in the past.
400	transaction-booking-start-before-end	The booking start time must be before the booking end time.

Transition transaction

HTTP request

POST /v1/api/transactions/transition

Example request

# Example transition assiming a process with daily booking
# and preauthorization.
$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/transactions/transition' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075"
  "transition": "transition/accept",
  "params": {}
}'

// Example transition assiming a process with daily booking
// and preauthorization.
sdk.transactions.transition({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  transition: "transition/accept",
  params: {}
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/accept",
      "lastTransitionedAt": "2018-03-27T13:35:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4,
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        },
        {
          "transition": "transition/accept",
          "createdAt": "2018-03-27T13:35:03.100Z",
          "by": "provider"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/accept",
      lastTransitionedAt: new Date("2018-03-27T13:35:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        },
        {
          transition: "transition/accept",
          createdAt: new Date("2018-03-27T13:35:03.100Z"),
          by: "provider"
        }
      ]
    }
  }
}

Command that transitions an existing transaction to a new state via a given transition.

Depending on the process definition, it may be that only one party of the transaction can perform a given transition. The authenticated user must be the authorized to perform the transition or the command will fail.

Body parameters

Parameter	Description
id	(uuid) The ID of the transaction.
transition	(string) The name of one of your transaction process' possible next transitions for the current transaction state.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
402	transaction-payment-failed	Payment information was invalid or the payment was rejected by Stripe. Additional information can be found in the error `meta.stripeMessage`, `meta.stripeCode` and `meta.stripeDeclineCode`. See also Stripe errors documentation.
403	forbidden	The authenticated user is not authorized to perform the given transition.
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible next transitions for the current transaction state.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-locked	The transaction is currently locked by another operation. Try again, but consider that it's likely that the transaction has already transitioned to a different state.
409	transaction-provider-banned-or-deleted	The provider in the transaction is banned or deleted and the transaction cannot be transitioned.
409	transaction-customer-banned-or-deleted	The customer in the transaction is banned or deleted and the transaction cannot be transitioned.

Speculatively transition transaction

HTTP request

POST /v1/api/transactions/transition_speculative

Example request

# Example speculative transition assiming a process with daily booking
# and preauthorization.
$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/transactions/transition_speculative' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "id": "ef98e897-5b81-49a5-aca6-01d9759df075"
  "transition": "transition/accept",
  "params": {}
}'

// Example speculative transition assiming a process with daily booking
// and preauthorization.
sdk.transactions.transitionSpeculative({
  id: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  transition: "transition/accept",
  params: {}
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "ef98e897-5b81-49a5-aca6-01d9759df075",
    "type": "transaction",
    "attributes": {
      "createdAt": "2018-03-27T12:30:02.000Z",
      "processName": "preauth-with-nightly-booking",
      "processVersion": 3,
      "lastTransition": "transition/accept",
      "lastTransitionedAt": "2018-03-27T13:35:03.100Z",
      "payinTotal": {
        "amount": 6360,
        "currency": "USD"
      },
      "payoutTotal": {
        "amount": 5724,
        "currency": "USD"
      },
      "lineItems": [
        {
          "code": "line-item/day",
          "quantity": 4
          "units": 2,
          "seats": 2,
          "reversal": false,
          "unitPrice": {
            "amount": 1590,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": 6360,
            "currency": "USD"
          },
          "includeFor": [
            "customer",
            "provider"
          ]
        },
        {
          "code": "line-item/provider-commission",
          "percentage": -10.0,
          "reversal": false,
          "unitPrice": {
            "amount": 6360,
            "currency": "USD"
          },
          "lineTotal": {
            "amount": -636,
            "currency": "USD"
          },
          "includeFor": [
            "provider"
          ]
        }
      ],
      "protectedData": {},
      "transitions": [
        {
          "transition": "transition/request",
          "createdAt": "2018-03-27T12:30:03.100Z",
          "by": "customer"
        },
        {
          "transition": "transition/accept",
          "createdAt": "2018-03-27T13:35:03.100Z",
          "by": "provider"
        }
      ]
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "ef98e897-5b81-49a5-aca6-01d9759df075"},
    type: "transaction",
    attributes: {
      createdAt: new Date("2018-03-27T12:30:02.000Z"),
      processName: "preauth-with-nightly-booking",
      processVersion: 3,
      lastTransition: "transition/accept",
      lastTransitionedAt: new Date("2018-03-27T13:35:03.100Z"),
      payinTotal: {
        amount: 6360,
        currency: "USD"
      },
      payoutTotal: {
        amount: 5724,
        currency: "USD"
      },
      lineItems: [
        {
          code: "line-item/day",
          quantity: 4,
          units: 2,
          seats: 2,
          reversal: false,
          unitPrice: {
            amount: 1590,
            currency: "USD"
          },
          lineTotal: {
            amount: 6360,
            currency: "USD"
          },
          includeFor: [
            "customer",
            "provider"
          ]
        },
        {
          code: "line-item/provider-commission",
          percentage: -10.0,
          reversal: false,
          unitPrice: {
            amount: 6360,
            currency: "USD"
          },
          lineTotal: {
            amount: -636,
            currency: "USD"
          },
          includeFor: [
            "provider"
          ]
        }
      ],
      protectedData: {},
      transitions: [
        {
          transition: "transition/request",
          createdAt: new Date("2018-03-27T12:30:03.100Z"),
          by: "customer"
        },
        {
          transition: "transition/accept",
          createdAt: new Date("2018-03-27T13:35:03.100Z"),
          by: "provider"
        }
      ]
    }
  }
}

Command that simulates transitioning an existing transaction to a new state. The transition is not actually performed and the transaction state is not changed. This command can be used to validate the parameters or to get updated transaction price breakdown (via lineItems), as if a real transition were performed.

Body parameters

The parameters for this command are exactly the same as for the /transactions/transition command.

Parameter	Description
id	(uuid) The ID of the transaction.
transition	(string) The name of one of your transaction process' possible next transitions for the current transaction state.
params	(object) The parameters for the transition, according to your transaction process definition.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Common errors

HTTP status code	Error code	Description
403	forbidden	The authenticated user is not authorized to perform the given transition.
409	transaction-invalid-transition	The given transition is not defined in the process or it is not one of the possible next transitions for the current transaction state.
409	transaction-invalid-action-sequence	The given transition cannot be executed because the action sequence is invalid and some action precondition is not met. The problem relates to the process description as a whole rather than just the transition in question.
409	transaction-locked	The transaction is currently locked by another operation. Try again, but consider that it's likely that the transaction has already transitioned to a different state.
409	transaction-provider-banned-or-deleted	The provider in the transaction is banned or deleted and the transaction cannot be transitioned.
409	transaction-customer-banned-or-deleted	The customer in the transaction is banned or deleted and the transaction cannot be transitioned.

Process transitions

API prefix

/v1/api/process_transitions

Example resource

{
  "data": {
    "id": "e55389df-f0e8-494d-93aa-05d2bbb975d3",
    "type": "processTransition",
    "attributes": {
      "name": "transition/request",
      "actor": [
        "customer"
      ],
      "actions": [
        "tegel.action/create-booking",
        "tegel.action/calculate-tx-nightly-total-price",
        "tegel.action/calculate-tx-provider-commission",
        "tegel.action/stripe-create-charge"
      ],
      "params": {
        "req": {
          "listingId": "uuid",
          "bookingStart": "timestamp",
          "bookingEnd": "timestamp",
          "cardToken": "string"
        },
        "opt": null
      }
    }
  }
}

{
  data: {
    id: UUID {uuid: "e55389df-f0e8-494d-93aa-05d2bbb975d3"},
    type: "processTransition",
    attributes: {
      name: "transition/request",
      actor: [
        "customer"
      ],
      actions: [
        "tegel.action/create-booking",
        "tegel.action/calculate-tx-nightly-total-price",
        "tegel.action/calculate-tx-provider-commission",
        "tegel.action/stripe-create-charge"
      ],
      params: {
        req: {
          listingId: "uuid",
          bookingStart: "timestamp",
          bookingEnd: "timestamp",
          cardToken: "string"
        },
        opt: null
      }
    }
  }
}

The process_transition API resource type represents information about available transitions in a transaction process.

All /process_transition/* API endpoints require an authenticated user access token.

`processTransition` resource format

Attribute	Description
name	(string) The uniquely identifying name of the transition
actor	(array) Array of actor roles that are allowed to take initiate the transition. Available values are `customer`, `provider`, `operator` and `system`.
actions	(array) Array of actions that are executed when the transition is executed. This data is purely for informational purpose at this point. Action names are subject to change. See Transaction process.
params.req	(object) Mandatory requested parameters for the transition. Keys are parameter names and values are parameter types. Type can be one of: `uuid`, `string`, `integer`, `timestamp`, `boolean`, `object`, `money`, `["lineItem"]`. For more information about the `["lineItem"]` parameter type, see Custom pricing.
params.opt	(object) Same as params.req but these parameters are optional.

Query transitions

HTTP request

GET /v1/api/process_transitions/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/process_transitions/query?transactionId=ef98e897-5b81-49a5-aca6-01d9759df075' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.processTransitions.query({
  transactionId: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "83cc91f0-8135-4670-84a9-038149e34a0c",
      "type": "processTransition",
      "attributes": {
        "name": "transition/accept",
        "actor": [
          "provider"
        ],
        "actions": [
          "tegel.action/accept-booking",
          "tegel.action/stripe-capture-charge"
        ],
        "params": {
          "req": null,
          "opt": null
        }
      }
    },
    {
      "id": "933bb276-3c69-4c04-8e52-e7692dd5f5f4",
      "type": "processTransition",
      "attributes": {
        "name": "transition/expire",
        "actor": [
          "system"
        ],
        "actions": [
          "tegel.action/decline-booking",
          "tegel.action/calculate-full-refund",
          "tegel.action/stripe-refund-charge"
        ],
        "params": {
          "req": null,
          "opt": null
        }
      }
    },
    {
      "id": "69fe4f4d-a92b-4f98-b816-e172894eb09f",
      "type": "processTransition",
      "attributes": {
        "name": "transition/decline",
        "actor": [
          "provider"
        ],
        "actions": [
          "tegel.action/decline-booking",
          "tegel.action/calculate-full-refund",
          "tegel.action/stripe-refund-charge"
        ],
        "params": {
          "req": null,
          "opt": null
        }
      }
    }
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
    data: [
      {
        id: UUID {uuid: "83cc91f0-8135-4670-84a9-038149e34a0c"},
        type: "processTransition",
        attributes: {
          name: "transition/accept",
          actor: [
            "provider"
          ],
          actions: [
            "tegel.action/accept-booking",
            "tegel.action/stripe-capture-charge"
          ],
          params: {
            req: null,
            opt: null
          }
        }
      },
      {
        id: UUID {uuid: "933bb276-3c69-4c04-8e52-e7692dd5f5f4"},
        type: "processTransition",
        attributes: {
          name: "transition/expire",
          actor: [
            "system"
          ],
          actions: [
            "tegel.action/decline-booking",
            "tegel.action/calculate-full-refund",
            "tegel.action/stripe-refund-charge"
          ],
          params: {
            req: null,
            opt: null
          }
        }
      },
      {
        id: UUID {uuid: "69fe4f4d-a92b-4f98-b816-e172894eb09f"},
        type: "processTransition",
        attributes: {
          name: "transition/decline",
          actor: [
            "provider"
          ],
          actions: [
            "tegel.action/decline-booking",
            "tegel.action/calculate-full-refund",
            "tegel.action/stripe-refund-charge"
          ],
          params: {
            req: null,
            opt: null
          }
        }
      }
    ],
    meta: {
      totalItems: 3,
      totalPages: 1,
      page: 1,
      perPage: 100
    }
  }

Query next possible process transitions based on existing transaction or by last transition taken.

Query parameters

Parameter	Description
processAlias	(string, optional) Return next possible transitions for the transaction process identified by the processAlias.
lastTransition	(string, optional) Return next possible transitions in the process when the last taken transition was this. Can be combined only with processAlias.
transactionId	(uuid, optional) Return next possible transitions for the transaction identified by this id.

Exactly one of the parameters processAlias or transactionId must always be present.

Common errors

HTTP status code	Error code	Description
403	forbidden	The authenticated user is not authorized to access the data.
409	transaction-invalid-transition	The given transition is not defined in the process
409	transaction-unknown-alias	The given processAlias cannot be resolved to a process name and version

Bookings

Example resource

{
  "data": {
    "id": "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1",
    "type": "booking",
    "attributes": {
      "seats": 3,
      "start": "2018-04-20T00:00:00.000Z",
      "end": "2018-04-22T00:00:00.000Z",
      "displayStart": "2018-04-20T18:00:00.000Z",
      "displayEnd": "2018-04-22T10:00:00.000Z",
      "state": "accepted"
    }
  }
}

{
  data: {
    id: UUID {uuid: "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1"},
    type: "booking",
    attributes: {
      seats: 3,
      start: new Date("2018-04-20T00:00:00.000Z"),
      end: new Date("2018-04-22T00:00:00.000Z"),
      displayStart: new Date("2018-04-20T18:00:00.000Z"),
      displayEnd: new Date("2018-04-22T10:00:00.000Z"),
      state: "accepted"
    }
  }
}

The booking resource type represents information about a booking.

`booking` resource format

Attribute	Description
seats	(number) Integer number of booked seats.
start	(string, timestamp) The date and time the booking starts. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
end	(string, timestamp) The date and time the booking ends. The range is exclusive on the `end` side, i.e. the `end` is not reserved. This time is used to determine what interval is matched against the listing's availability and is reserved with the booking.
displayStart	(string, timestamp) The booking start display time. The display time is an arbitrary timestamp and can be different from the `start` time.
displayEnd	(string, timestamp) The booking end display time. The display time is an arbitrary timestamp and can be different from the `end` time.
state	(string) The state of the booking. See booking states.

Note that if your transaction process uses daily or nightly bookings, only the date component of the timestamp is relevant. In that case the time component of start and end timestamps is normalized to 00:00:00.000Z time but you have to interpret the timestamp in UTC time zone in order to get the correct date.

The booking displayStart and displayEnd times can optionally be set when a booking is created via a transaction. If omitted, the displayStart and displayEnd will have the same values as start and end respectively. If set, displayStart and displayEnd are stored and returned unmodified by the API (i.e. no normalization is performed for them for day- and night-based bookings, unlike the start and end times).

`booking` states

State	Reserves time slot	Description
pending	yes	A new booking that has been requested.
proposed	no	A new booking that has been proposed.
accepted	yes	A booking that has been accepted.
declined	no	A booking that has been declined before it was accepted.
cancelled	no	A booking that has been cancelled after it was accepted.

For more information about bookings, booking states and availability management, see Listing availability management.

`booking` relationships

Relationship	Resource type	Cardinality	Description
transaction	transaction	one	The transaction corresponding to a given booking. Supported nested relationships: `transaction.customer` and `transaction.customer.profileImage`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query bookings

HTTP request

GET /v1/api/bookings/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/bookings/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2018-11-27T00:00:00.000Z&end=2018-12-30T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.bookings.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-11-27T00:00:00.000Z"),
  end: new Date("2018-12-30T00:00:00.000Z")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1",
      "type": "booking",
      "attributes": {
        "seats": 3,
        "start": "2018-04-20T00:00:00.000Z",
        "end": "2018-04-22T00:00:00.000Z",
        "displayStart": "2018-04-20T18:00:00.000Z",
        "displayEnd": "2018-04-22T10:00:00.000Z",
        "state": "accepted"
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1"},
      type: "booking",
      attributes: {
        seats: 3,
        start: new Date("2018-04-20T00:00:00.000Z"),
        end: new Date("2018-04-22T00:00:00.000Z"),
        displayStart: new Date("2018-04-20T18:00:00.000Z"),
        displayEnd: new Date("2018-04-22T10:00:00.000Z"),
        state: "accepted"
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all bookings for a given listing and time range.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) The start date and time for the query range in ISO 8601 format. The start time must be between 366 days in the past and 366 days in the future.
end	(timestamp) The end date and time for the query range in ISO 8601 format. The end time must be after the `start` time and at most 366 days in the future and at most 90 days from the `start` time.
state	(string, optional) Comma-separated list of booking states. Return only bookings in one of the given states, or all bookings, if `state` filter is omitted. See `booking` states.

Time slots

Example resource

# Day-based time slot
{
  "data": {
    "id": "d479cd2d-5890-405a-b895-20a9a1ffdde7",
    "type": "timeSlot",
    "attributes": {
      "type": "time-slot/day",
      "seats": 3,
      "start": "2018-04-22T00:00:00.000Z",
      "end": "2018-04-23T00:00:00.000Z"
    }
  }
}

# Time-based time slot
{
  "data": {
    "id": "d479cd2d-5890-405a-b895-20a9a1ffdde8",
    "type": "timeSlot",
    "attributes": {
      "type": "time-slot/time",
      "seats": 3,
      "start": "2018-04-22T17:30:00.000Z",
      "end": "2018-04-23T10:15:00.000Z"
    }
  }
}

// Day-based time slot
{
  data: {
    id: UUID {uuid: "d479cd2d-5890-405a-b895-20a9a1ffdde7"},
    type: "timeSlot",
    attributes: {
      type: "time-slot/day",
      seats: 3,
      start: new Date("2018-04-22T00:00:00.000Z"),
      end: new Date("2018-04-23T00:00:00.000Z")
    }
  }
}

// Time-based time slot
{
  data: {
    id: UUID {uuid: "d479cd2d-5890-405a-b895-20a9a1ffdde8"},
    type: "timeSlot",
    attributes: {
      type: "time-slot/time",
      seats: 3,
      start: new Date("2018-04-22T17:30:00.000Z"),
      end: new Date("2018-04-23T10:15:00.000Z")
    }
  }
}

The timeSlot resource type represents information about a time interval available for booking. When your transaction process is configured so that overlapping bookings are not allowed (availability is observed when creating a booking), you can only create bookings that span over continuous time slots that have enough seats available for the booking.

As all API resources, timeSlot resources have IDs. However, their IDs are ephemeral and will change across requests.

`timeSlot` resource format

Attribute	Description
type	(string) The type of the slot. One of `time-slot/day` or `time-slot/time`.
seats	(number) Amount of seats available to be booked during the time slot. `seats` is always positive as time slots with no seats available are not returned in time slots queries.
start	(string, timestamp) The date and time the time slot starts in ISO 8601 format.
end	(string, timestamp) The date and time the time slot ends in ISO 8601 format. The range is exclusive on the `end` side.

`timeSlot` types

Type	Description
time-slot/day	The time slot represents a calendar day. The time component should be ignored. Its `start` timestamp is normalized to 00:00:00 UTC on the day and `end` timestamp is normalized to 00:00:00 UTC on the next day.
time-slot/time	The time slot represents a concrete time interval with absolute `start` and `end` times. The time interval may have arbitrary length.

Query time slots

HTTP request

GET /v1/api/timeslots/query

Example request

# Query available timeslots between 19th and 24th
# assuming there is a booking from 20th to 22nd.
$ curl 'https://flex-api.sharetribe.com/v1/api/timeslots/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2018-04-19T00:00:00.000Z&end=2018-04-24T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Query available timeslots between 19th and 24th
// assuming there is a booking from 20th to 22nd.
sdk.timeslots.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2018-04-19T00:00:00.000Z"),
  end: new Date("2018-04-24T00:00:00.000Z")
}).then(res => {
  // res.data comains the response data
});

Example response

{
  "data": [
    {
      "id": "d479cd2d-5890-405a-b895-20a9a1ffdde7",
      "type": "timeSlot",
      "attributes": {
        "type": "time-slot/day",
        "seats": 3,
        "start": "2018-04-19T00:00:00.000Z",
        "end": "2018-04-20T00:00:00.000Z"
      }
    },
    {
      "id": "2698b352-b7b5-4fd8-9303-31aa96957556",
      "type": "timeSlot",
      "attributes": {
        "type": "time-slot/day",
        "seats": 1,
        "start": "2018-04-22T00:00:00.000Z",
        "end": "2018-04-23T00:00:00.000Z"
      }
    },
    {
      "id": "4f0ae8dc-f08e-46da-935d-f33aab6459b0",
      "type": "timeSlot",
      "attributes": {
        "type": "time-slot/day",
        "seats": 10,
        "start": "2018-04-23T00:00:00.000Z",
        "end": "2018-04-24T00:00:00.000Z"
      }
    }
  ],
  "meta": {
    "totalItems": 3,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

{
  data: [
    {
      id: UUID {uuid: "d479cd2d-5890-405a-b895-20a9a1ffdde7"},
      type: "timeSlot",
      attributes: {
        type: "time-slot/day",
        seats: 3,
        start: new Date("2018-04-19T00:00:00.000Z"),
        end: new Date("2018-04-20T00:00:00.000Z")
      }
    },
    {
      id: UUID {uuid: "2698b352-b7b5-4fd8-9303-31aa96957556"},
      type: "timeSlot",
      attributes: {
        type: "time-slot/day",
        seats: 1,
        start: new Date("2018-04-22T00:00:00.000Z"),
        end: new Date("2018-04-23T00:00:00.000Z")
      }
    },
    {
      id: UUID {uuid: "4f0ae8dc-f08e-46da-935d-f33aab6459b0"},
      type: "timeSlot",
      attributes: {
        type: "time-slot/day",
        seats: 10,
        start: new Date("2018-04-23T00:00:00.000Z"),
        end: new Date("2018-04-24T00:00:00.000Z")
      }
    }
  ],
  meta: {
    totalItems: 3,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query available time slots for given listing.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) Start time of the interval to query for in ISO 8601 format. The start time must be between one day in the past and 366 days in the future.
end	(timestamp) End time of the interval to query for (exclusive) in ISO 8601 format. The end time must be after the `start` time and at most either 366 days in the future and at most 90 days from the `start` time.

Maximum value for the perPage parameter when paginating time slots query responses is 500 instead of the standard 100. See pagination.

Stock

API prefix

/v1/api/stock/

Example resource

{
  "data": {
    "id": "22e9df61-a655-4491-bdfc-494e95072f58",
    "type": "stock",
    "attributes": {
      "quantity": 10
    }
  }
}

{
  data: {
    id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
    type: "stock",
    attributes: {
      quantity: 10
    }
  }
}

The stock API resource type represents information about the available stock of a listing. stock resources are currently only available via the currentStock relationship of listing and ownListing resources.

All /stock/* API endpoints require an authenticated user access token.

`stock` resource format

Attribute	Description
quantity	(integer) The quantity of available stock. Under normal operation this number is non-negative. See Negative stock quantity for more details.

Compare and set total stock

HTTP request

POST /v1/api/stock/compare_and_set

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stock/compare_and_set?expand=true' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "oldTotal": 8,
  "newTotal": 10
}'

sdk.stock.compareAndSet({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  oldTotal: 8,
  newTotal: 10
}, {
  expand: true
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "22e9df61-a655-4491-bdfc-494e95072f58",
    "type": "stock",
    "attributes": {
      "quantity": 10
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
    type: "stock",
    attributes: {
      quantity: 10
    }
  }
}

Command that sets the total available stock for a listing. Internally, the command creates a new stock adjustment, such that the listing's total available stock becomes the given newTotal quantity.

This command guarantees that the stock adjustment will be created if and only if the listing's available stock quantity prior to the command matches the given oldTotal quantity.

If oldTotal and newTotal are equal, a new stock adjustment is not created and the command is a no-op.

The listing must belong to the authenticated user.

Body parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
oldTotal	(integer) The quantity of listing stock that the listing must have prior to the command execution in order for the new total to be set. Must be set to `null` if the listing does not have stock defined at all.
newTotal	(integer) The total quantity of stock that the listing will have after the command is successfully executed. Must be a non-negative number.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stock adjustments

API prefix

/v1/api/stock_adjustments/

Example resource

{
  "data": {
    "id": "daec15c8-506f-40c3-828f-a1f064c06592",
    "type": "stockAdjustment",
    "attributes": {
      "at": "2021-09-07T10:00:00.000Z",
      "quantity": 2
    }
  }
}

{
  data: {
    id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
    type: "stockAdjustment",
    attributes: {
      at: new Date("2021-09-07T10:00:00.000Z"),
      quantity: 2
    }
  }
}

The stockAdjustment API resource type represents information about a change in the quantity of available stock of a listing. The total available stock is the sum of all adjustments.

Stock adjustments are immutable and will never change.

All /stock_adjustments/* API endpoints require an authenticated user access token.

`stockAdjustment` resource format

Attribute	Description
at	(string, timestamp) The date and time when the stock adjustment takes effect in ISO 8601 format.
quantity	(integer) The quantity of the adjustment. A positive number indicates increase in available stock, while a negative number indicates a reduction. A quantity of 0 is only possible for an initial stock adjustment that sets the listing's available stock to 0.

`stockAdjustment` relationships

Relationship	Resource type	Cardinality	Description
ownListing	ownListing	one	The listing to which the stock adjustment applies. Supported nested relationships: `ownListing.currentStock`
stockReservation	stockReservation	one	(optional) The stock reservation that caused the stock adjustment, if any. Supported nested relationships: `stockReservation.transaction`, `stockReservation.transaction.customer`, `stockReservation.transaction.customer.profileImage`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query stock adjustments

HTTP request

GET /v1/api/stock_adjustments/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/stock_adjustments/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&start=2021-09-07T00:00:00.000Z&end=2021-09-10T00:00:00.000Z' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.stockAdjustments.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  start: new Date("2021-09-07T00:00:00.000Z"),
  end: new Date("2021-09-10T00:00:00.000Z")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "daec15c8-506f-40c3-828f-a1f064c06592",
      "type": "stockAdjustment",
      "attributes": {
        "at": "2021-09-07T10:00:00.000Z",
        "quantity": 2
      }
    }
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 5,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
      type: "stockAdjustment",
      attributes: {
        at: new Date("2021-09-07T10:00:00.000Z"),
        quantity: 2
      }
    }
    {...},
    {...}
  ],
  meta: {
    totalItems: 5,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all the stock adjustments of a given listing for a given time range (i.e. have at timestamp within the given range). The results are ordered by the stock adjustment's at timestamp in increasing order (i.e. oldest stock adjustments are returned first). The listing must belong to the authenticated user.

Include the ownListing.currentStock nested relationship in order to obtain the current total listing stock at the time of query. Since past stock adjustments are immutable, this allows to compute the available stock at any past point in time by summing up the applicable adjustments starting from the current total available stock.

Query parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
start	(timestamp) Filter stock adjustments by `at` time. Only stock adjustments with `at` time greater than or equal to the given timestamp are returned. The timestamp is in ISO 8601 format. The start time must be between 366 days in the past and 1 day in the future.
end	(timestamp) Filter stock adjustments by `at` time. Only stock adjustments with `at` time less than the given timestamp are returned. The timestamp is in ISO 8601 format. The end time must be after the `start` time and at most 1 day in the future and at most 366 days from the `start` time.

Create stock adjustment

HTTP request

POST /v1/api/stock_adjustments/create

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/stock_adjustments/create?expand=true,include=ownListing.currentStock' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "listingId": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
  "quantity": 2
}'

sdk.stockAdjustments.create({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f"),
  quantity: 2
}, {
  expand: true,
  include: ["ownListing.currentStock"]
}).then(res => {
  // res.data
});

Example response

{
  "data": {
    "id": "daec15c8-506f-40c3-828f-a1f064c06592",
    "type": "stockAdjustment",
    "attributes": {
      "at": "2021-09-07T10:00:00.000Z",
      "quantity": 2
    },
    "relationships": {
      "ownListing": {
          "data": {"id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f", "type": "ownListing"}
      }
    }
  },
  "included": [
    {
      "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
      "type": "ownListing",
      "attributes": {...}
      "relationships": {
        "currentStock": {
          "data": {"id": "22e9df61-a655-4491-bdfc-494e95072f58", "type": "stock"}
        }
      }
    },
    {
      "id": "22e9df61-a655-4491-bdfc-494e95072f58",
      "type": "stock",
      "attributes": {
        "quantity": 10
      }
    }
  ]
}

// res.data
{
  data: {
    id: UUID {uuid: "daec15c8-506f-40c3-828f-a1f064c06592"},
    type: "stockAdjustment",
    attributes: {
      at: new Date("2021-09-07T10:00:00.000Z"),
      quantity: 2
    },
    relationships: {
      ownListing: {
        data: {id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"}, type: "ownListing"}
      }
    }
  },
  included: [
    {
      id: UUID {uuid: "c6ff7190-bdf7-47a0-8a2b-e3136e74334f"},
      type: "ownListing",
      attributes: {...},
      relationships: {
        currentStock: {
          data: {id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"}, type: "stock"}
        }
      }
    },
    {
      id: UUID {uuid: "22e9df61-a655-4491-bdfc-494e95072f58"},
      type: "stock",
      attributes: {
        quantity: 10
      }
    }
  ]
}

Command that creates a new stock adjustment for a given listing. The new adjustment takes effect immediately. The listing must belong to the authenticated user.

Include the ownListing.currentStock nested relationship in order to obtain the current total listing stock with the new adjustment taken into account.

Body parameters

Parameter	Description
listingId	(uuid) The ID of the listing.
quantity	(integer) The quantity of the adjustment. A positive number indicates increase in available stock, while a negative number indicates a reduction. It is not possible to create stock adjustments with 0 quantity.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Stock reservations

API prefix

/v1/api/stock_reservations/

Example resource

{
  "data": {
    "id": "2b78155f-fba6-491e-b842-d83d23ea657e",
    "type": "stockReservation",
    "attributes": {
      "quantity": 2,
      "state": "pending"
    }
  }
}

{
  data: {
    id: UUID {uuid: "2b78155f-fba6-491e-b842-d83d23ea657e"},
    type: "stockReservation",
    attributes: {
      quantity: 2,
      state: "pending"
    }
  }
}

The stockReservation API resource type represents information about a stock reservation.

`stockReservation` resource format

Attribute	Description
quantity	(integer) The quantity of reserved stock.
state	(string) The state of the stock reservation. See stock reservation states.

Stock reservation states

State	Reserves stock	Description
pending	yes	A new stock reservation that has been requested.
proposed	no	A new stock reservation that has been proposed.
accepted	yes	A stock reservation that has been accepted.
declined	no	A stock reservation that has been declined before it was accepted.
cancelled	no	A stock reservation that has been cancelled after it was accepted.

For more information, see also stock reservation states section in the documentation the transaction process actions related to stock reservations.

`stockReservation` relationships

Relationship	Resource type	Cardinality	Description
transaction	transaction	one	The transaction corresponding to the stock reservation. Supported nested relationships: `transaction.customer`, `transaction.customer.profileImage`.

Reviews

API prefix

/v1/api/reviews

Example resource

{
  "data": {
    "id": "81a0170a-ecc2-4fe1-9aae-e86226023717",
    "type": "review",
    "attributes": {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": "2018-04-25T11:10:14.123Z",
      "deleted": "false"
    }
  }
}

{
  data: {
    id: UUID {uuid: "81a0170a-ecc2-4fe1-9aae-e86226023717"},
    type: "review",
    attributes: {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": new Date("2018-04-25T11:10:14.123Z"),
      "deleted": "false"
    }
  }
}

The review resource format represent reviews posted by transaction parties about one another. Reviews are only posted during a transaction through the transaction process and as such, the Marketplace API does not contain commands for posting new reviews.

`review` resource format

Attribute	Description
type	(string) The review type - one of `ofProvider` or `ofCustomer`. `ofProvider` reviews are written by customers in a transaction and are considered as reviews about both the provider and the listing in that transaction. `ofCustomer` reviews are written by providers and are about the customer in the transaction.
state	(string) The review state - one of `public` or `pending`. If a review is in `pending` state, its `content` and `rating` attributes are always returned as `null`. Reviews are created and made public through your transaction process.
rating	(number, integer) The rating given with the review. An integer from 1 to 5, inclusive.
content	(string) The content of the view.
createdAt	(string, timestamp) The date and time the review was written, in ISO 8601 format.
deleted	(boolean) Flag indicating whether the review has been deleted. If true, all other attributes of the review will be returned as default values (false for booleans and null for all else). Used when relationship requires a deleted review.

`review` relationships

Relationship	Resource type	Cardinality	Description
author	user	one	The user that wrote the review. Supported nested relationships: `author.profileImage`.
listing	listing	one	The listing that the review is about. The relationship is available only for reviews of type `ofProvider`.
subject	user	one	The user that the review is about. Supported nested relationships: `subject.profileImage`.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Show review

HTTP request

GET /v1/api/reviews/show

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/reviews/show?id=81a0170a-ecc2-4fe1-9aae-e86226023717' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.reviews.show({
  id: new UUID("81a0170a-ecc2-4fe1-9aae-e86226023717")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "81a0170a-ecc2-4fe1-9aae-e86226023717",
    "type": "review",
    "attributes": {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": "2018-04-25T11:10:14.123Z"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "81a0170a-ecc2-4fe1-9aae-e86226023717"},
    type: "review",
    attributes: {
      "type": "ofProvider",
      "state": "public",
      "rating": 5,
      "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
      "createdAt": new Date("2018-04-25T11:10:14.123Z")
    }
  }
}

Query returning data about a given review.

Query parameters

Parameter	Description
id	(uuid) The review ID.

Query reviews

HTTP request

GET /v1/api/reviews/query

Example request

# Query all reviews about given listing
$ curl 'https://flex-api.sharetribe.com/v1/api/reviews/query?listingId=c6ff7190-bdf7-47a0-8a2b-e3136e74334f' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

// Query all reviews about given listing
sdk.reviews.query({
  listingId: new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f'")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "6cc2ea02-0695-42d1-9b7e-f8608e9aee73",
      "type": "review",
      "attributes": {
        "type": "ofProvider",
        "state": "pending",
        "rating": null,
        "content": null,
        "createdAt": "2018-04-29T10:18:43.124Z"
      }
    },
    {
      "id": "81a0170a-ecc2-4fe1-9aae-e86226023717",
      "type": "review",
      "attributes": {
        "type": "ofProvider",
        "state": "public",
        "rating": 5,
        "content": "The bike was awesome and everything went smoothly.\n\nThanks!",
        "createdAt": "2018-04-25T11:10:14.123Z"
      }
    },
    {...},
    {...}
  ],
  "meta": {
    "totalItems": 4,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "6cc2ea02-0695-42d1-9b7e-f8608e9aee73"},
      type: "review",
      attributes: {
        type: "ofProvider",
        state: "pending",
        rating: null,
        content: null,
        createdAt: new Date("2018-04-29T10:18:43.124Z")
      }
    },
    {
      id: UUID {uuid: "81a0170a-ecc2-4fe1-9aae-e86226023717"},
      type: "review",
      attributes: {
        type: "ofProvider",
        state: "public",
        rating: 5,
        content: "The bike was awesome and everything went smoothly.\n\nThanks!",
        createdAt: new Date("2018-04-25T11:10:14.123Z")
      }
    },
    {...},
    {...}
  ],
  meta: {
    totalItems: 4,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query returning all reviews for a given transaction, listing or user, with optional filtering by review type and state. Results are sorted by review's createdAt time in descending order (i.e. newest reviews are returned first).

Query parameters

Parameter	Description
transactionId	(uuid, optional*) Query all reviews posted during given transaction.
listingId	(uuid, optional*) Query all reviews about given listing. All reviews about the listing are `ofProvider` type.
subjectId	(uuid, optional*) Query all reviews about given user.
type	(string, optional) Either `ofCustomer` or `ofProvider`. The query will return only reviews of the given type.
state	(string, optional) Comma separated list of review states. The query will return only reviews in the given state.

* Note that this query requires that exactly one of the parameters transactionId, listingId or subjectId is given.

Messages

API prefix

/v1/api/messages

Example resource

{
  "data": {
    "id": "efe37293-5e58-4f8d-8507-64616e34d22e",
    "type": "message",
    "attributes": {
      "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      "createdAt": "2018-03-28T09:12:58.866Z"
    }
  }
}

{
  data: {
    id: UUID {uuid: "efe37293-5e58-4f8d-8507-64616e34d22e"},
    type: "message",
    attributes: {
      content: "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      createdAt: new Date("2018-03-28T09:12:58.866Z")
    }
  }
}

The message resource type represents transaction messages that are sent between users as part of a conversation about transaction. Messages are always linked to a transaction. However, unlike bookings and reviews, messages are sent via an explicit API command and have no effect on transaction state or transitions.

`message` resource format

Attribute	Description
content	(string) The message content.
createdAt	(string, timestamp) The date and time the message was sent in ISO 8601 format.

`message` relationships

Relationship	Resource type	Cardinality	Description
sender	user	one	The user that sent the message. Supported nested relationships: `sender.profileImage`.
transaction	transaction	one	The transaction that the message refers to.

Use the include query parameter to specify which relationships are included. Learn more about including related resources.

Query messages

HTTP request

GET /v1/api/messages/query

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/messages/query?transactionId=ef98e897-5b81-49a5-aca6-01d9759df075' \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.messages.query({
  transactionId: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075")
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "1ce7eeb5-f60b-4119-bf37-d5a6f04e1dd3",
      "type": "message",
      "attributes": {
        "content": "Sure! I haven't changed them yet.",
        "createdAt": "2018-03-28T10:04:01.324Z"
      }
    },
    {
      "id": "efe37293-5e58-4f8d-8507-64616e34d22e",
      "type": "message",
      "attributes": {
        "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
        "createdAt": "2018-03-28T09:12:58.866Z"
      }
    }
  ],
  "meta": {
    "totalItems": 2,
    "totalPages": 1,
    "page": 1,
    "perPage": 100
  }
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "1ce7eeb5-f60b-4119-bf37-d5a6f04e1dd3"},
      type: "message",
      attributes: {
        content: "Sure! I haven't changed them yet.",
        createdAt: new Date("2018-03-28T10:04:01.324Z")
      }
    },
    {
      id: UUID {uuid: "efe37293-5e58-4f8d-8507-64616e34d22e"},
      type: "message",
      attributes: {
        content: "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
        createdAt: new Date("2018-03-28T09:12:58.866Z")
      }
    }
  ],
  meta: {
    totalItems: 2,
    totalPages: 1,
    page: 1,
    perPage: 100
  }
}

Query that returns all messages in a given transaction. The results are sorted by message's createdAt time in descending order (i.e. newest messages are returned first).

Query parameters

Parameter	Description
transactionId	(uuid) The ID of the transaction.

Send message

HTTP request

POST /v1/api/messages/send

Example request

$ curl -X POST 'https://flex-api.sharetribe.com/v1/api/messages/send' \
    -H 'Accept: application/json' \
    -H 'Content-type: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN' \
    -d '{
  "transactionId": "ef98e897-5b81-49a5-aca6-01d9759df075",
  "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back."
}'

sdk.messages.send({
  transactionId: new UUID("ef98e897-5b81-49a5-aca6-01d9759df075"),
  content: "Hello,\n\nDoes the bike have winter tyres? Snow is back."
}, {
  expand: true
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": {
    "id": "efe37293-5e58-4f8d-8507-64616e34d22e",
    "type": "message",
    "attributes": {
      "content": "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      "createdAt": "2018-03-28T09:12:58.866Z"
    }
  }
}

// res.data
{
  data: {
    id: UUID {uuid: "efe37293-5e58-4f8d-8507-64616e34d22e"},
    type: "message",
    attributes: {
      content: "Hello,\n\nDoes the bike have winter tyres? Snow is back.",
      createdAt: new Date("2018-03-28T09:12:58.866Z)"
    }
  }
}

Command that sends a new message in a given transaction. Messages are always sent as part of a transaction and can be sent at any time after the transaction has been initiated, regardless of its state.

An email notification about the new message is sent to the receiving party.

Body parameters

Parameter	Description
transactionId	(uuid) The ID of the transaction.
content	(string) The content of the message. Must be between 1 and 5000 characters.

By default, POST endpoints only return a resource reference. The expand parameter can be used to return the full resource (with attributes). Learn more about common query parameters.

Sitemap data

API prefix

/v1/api/sitemap_data/

The API endpoints under the /sitemap_data/ prefix return different resource types, depending on the endpoint. See individual endpoint reference below.

The sitemap data resources represent data about other marketplace entities (such as listings or assets) in a minimal and efficient format.

The data returned by all /sitemap_data/ API endpoints is cached up to 24 hours and does not update in real time.

Query list of listings

HTTP request

GET /v1/api/sitemap_data/query_listings

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/sitemap_data/query_listings \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.sitemapData.queryListings().then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "8df4ee42-e2bc-4f02-ae93-3addf43a715b",
      "type": "listingSitemapEntry"
    }
    {...},
    {...}
  ]
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "8df4ee42-e2bc-4f02-ae93-3addf43a715b"},
      type: "listingSitemapEntry"
    }
    {...},
    {...}
  ]
}

Query IDs of up to 10 000 most recently created listings in the marketplace. This endpoint returns listingSitemapEntry resources, representing the IDs of listings. The endpoint returns data for the most recently created listings in descending order of the listing creation time.

This endpoint does not return any meta and does not support pagination.

`listingSitemapEntry` resource format

The listingSitemapEntry resource does not contain any attributes. The id of the resource matches the ID of the corresponding listing.

Query parameters

The endpoint does not accept any query parameters.

Query list of assets

HTTP request

GET /v1/api/sitemap_data/query_assets

Example request

$ curl 'https://flex-api.sharetribe.com/v1/api/sitemap_data/query_assets?pathPrefix=/content/pages/ \
    -H 'Accept: application/json' \
    -H 'Authorization: bearer ACCESS_TOKEN'

sdk.sitemapData.queryListings({
  pathPrefix: "/content/pages/"
}).then(res => {
  // res.data contains the response data
});

Example response

{
  "data": [
    {
      "id": "21672aa6-0c42-487e-979d-c75644d5e377",
      "type": "assetSitemapEntry",
      "attributes": {
        "assetPath": "/content/pages/about.json"
      }
    }
    {...},
    {...}
  ]
}

// res.data
{
  data: [
    {
      id: UUID {uuid: "21672aa6-0c42-487e-979d-c75644d5e377"},
      type: "assetSitemapEntry",
      attributes: {
        assetPath: "/content/pages/about.json"
      }
    }
    {...},
    {...}
  ]
}

Query data about up to 1 000 most recently created JSON assets in a given path prefix. The query targets always the latest alias of the asset tree version. The endpoint returns data for the most recently created assets in descending order of the asset creation time.

The endpoint returns only assets of type JSON (i.e. image assets are not returned).

The asset contents are not returned by this endpoint. Use the Asset Delivery API to retrieve them.

This endpoint does not return any meta and does not support pagination.

`listingSitemapEntry` resource format

Attribute	Description
assetPath	(string) The absolute path of the asset.

Query parameters

Parameter	Description
pathPrefix	(string) An absolute path prefix. Only assets that have a path starting with the given prefix are returned. Currently, this parameter must always have the value `/content/pages/`.

Marketplace API reference

Authentication

Sharetribe SDK

Logging in

Logging out

Rate limits

Marketplace

marketplace resource format

Show marketplace

Users

user resource format

user states

user relationships

Show user

Query parameters

Current user

currentUser resource format

currentUser identity provider

currentUser states

currentUser permissionSet

currentUser relationships

Show current user

Delete user

Body parameters

Common errors

Create user

Body parameters

Common errors

Create user with an identity provider

Body parameters

Common errors

Update user profile

Body parameters

Common errors

Change password

Body parameters

Common errors

Change email address

Body parameters

Common errors

Verify email address

Body parameters

Common errors

Send verification email

Common errors

DEPRECATED: Create Stripe account

Body parameters

Common errors

DEPRECATED: Update Stripe account

Body parameters

Common errors

Password reset

Request password reset

Body parameters

Common errors

Reset password

Body parameters

Common errors

Stripe Account

stripeAccount resource format

Fetch Stripe account

Create Stripe account

Body parameters

Common errors

Update Stripe account

Body parameters

Common errors

Stripe Account Links

stripeAccountLink resource format

Create Stripe Account Link

Body parameters

Common errors

Stripe Persons

stripeAccount resource format

Create Stripe person

Body parameters

Common errors

Stripe Setup Intents

stripeSetupIntent resource format

Create Stripe Setup Intents

`marketplace` resource format

`user` resource format

`user` states

`user` relationships

`currentUser` resource format

`currentUser` identity provider

`currentUser` states

`currentUser` permissionSet

`currentUser` relationships

`stripeAccount` resource format

`stripeAccountLink` resource format

`stripeAccount` resource format

`stripeSetupIntent` resource format

`stripeCustomer` resource format

`stripeCustomer` relationships

`stripeCustomer` resource format

`listing` resource format

`listing` states

`listing` availability plan

`listing` relationships

`ownListing` resource format

`ownListing` states

`ownListing` availability plan

`ownListing` relationships

`availabilityException` resource format

`availabilityException` relationships

`image` resource format