NAV Navbar
JavaScript curl
  • Introduction
  • Authentication
  • Errors
  • Response format
  • Including related resources
  • Sparse attributes
  • Pagination
  • Common query parameters
  • Marketplace
  • Users
  • Current user
  • Password reset
  • Listings
  • Own listings
  • Availability exceptions
  • Images
  • Transactions
  • Process transitions
  • Bookings
  • Time slots
  • Reviews
  • Messages
  • Introduction

    The Sharetribe Flex Marketplace API is an HTTP API. The API supports both JSON and Transit formats. The easiest way to access the API is by using the Sharetribe Flex SDK.

    Authentication

    Example request:

    $ curl -X GET 'https://flex-api.sharetribe.com/v1/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 Flex 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 Flex SDK

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

    Sharetribe Flex SDK is at the moment available for JavaScript.

    The Sharetribe Flex SDK makes it easier to authenticate to the Sharetribe Flex 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.

    Errors

    Example error response

    {
      "errors": [
        {
          "id": "2a67748f-33d4-4293-8323-5a1d256e83b8",
          "status": 400,
          "code": "validation-invalid-value",
          "title": "Invalid value",
          "details": "lat must be a valid number for a latitude.",
          "source": {
            "path": ["location", "lat"],
            "type": "body"
          }
        },
        {
          "id": "2a67748f-33d4-4293-8323-5a1d256e83b7",
          "status": 400,
          "code": "validation-missing-key",
          "title": "Missing required key.",
          "source": {
            "path": ["title"],
            "type": "body"
          }
        },
        {
          "id": "2a67748f-33d4-4293-8323-5a1d256e83b9",
          "status": 400,
          "code": "validation-disallowed-key",
          "title": "Disallowed key.",
          "source": {
            "path": ["price", "sum"],
            "type": "body"
          }
        },
        {
          "id": "2a67748f-33d4-4293-8323-5a1d256e83ba",
          "status": 400,
          "code": "validation-disallowed-key",
          "title": "Disallowed key.",
          "source": {
            "path": ["title"],
            "type": "query"
          }
        }
      ]
    }
    

    In case of an error, the API returns a top-level key errors in the response with an array of one or more error objects and the HTTP response will have appropriate 4xx or 5xx status code. Responses with 5xx status codes are not guaranteed to have a valid body.

    Error format

    Attribute Description
    id (uuid) The error ID. This is unique ID for each instance of an error.
    status (number) HTTP status code for the error.
    code (string) Error code. Clients can use the error code to determine what the error was. See the list of error codes.
    title (string) Human readable error title. The title is always the same for a given error code.
    details (string, optional) Human readable explanation of the error. This is an optional attribute and, when present, is intended to be used to aid API client development and debugging. API clients should not reply on the presence or the contents of this attribute.
    source (object, optional) Indicates the request parameter (in query string or body) that caused the error, when possible.
    source.path (array) Array of strings, representing the (nested) path to a key in the request body or the name of the query parameter that the error is attributed to.
    source.type (string) Indicates whether the path represents a body or query parameter.

    HTTP status codes

    The following table describes some commonly used HTTP status codes.

    HTTP status code Description
    400 Bad request. Typically used to indicate that the request contained invalid query or body parameter or syntax.
    401 Unauthorized. The API request was made with invalid or expired access token. The client must obtain a valid and fresh access token via the Authentication API.
    402 Payment failed. Used to indicate error during payment processing. See Transactions.
    403 Forbidden. The authenticated or anonymous user does not have access to the requested resource or API endpoint.
    404 Not found. Returned by query endpoints when the requested resource is not found. Note that queries that return multiple resources DO NOT return a 404 error when no resource matches the query parameters. Instead, they return response with empty data array. See Response format.
    409 Conflict. The command can not be completed. This is commonly caused by a missing resource, which is required by the command, a resource in an unexpected state, logic error in the request, etc.
    500 Internal server error. The API failed to process the request due to unexpected error.

    Response format

    Example basic response

    {
      "data": {
        "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
        "type": "user",
        "attributes": {
          "banned": false,
          "profile": {
            "displayName": "Joe D",
            "abbreviatedName": "JD",
            "bio": "Hello, I'm Joe."
          }
        }
      }
    }
    

    An API resource is always identified by and id and type. The id is always a UUID. The API reference describes each type and it's attributes in more detail.

    Each resource type has its own set of attributes. These attributes are returned by default for API read requests (GET). Responses for API write requests (POST) only return a resource reference (an object with only id and type keys). Clients may request write requests to return the full attribute set by adding expand=true as query parameter. Additionally, clients can control the set of returned attributes for each resource type in the API responses via sparse attribute queries. Using sparse attributes is highly recommended because it allows for smaller and faster API responses.

    Each requested attribute (whether because it is in the default set of attributes, or because it was explicitly requested) is present in the API response. If data for that attribute did not exist, the value is populated with a default null value.

    A resource may have a set of relationships to other resources. For instance, listing has author relationship to a user resource. Clients may request that the API also returns data about related resources in the response.

    Responses may contain metadata in the meta top-level response key. The meta is an object that may contain information about the response, such as pagination information.

    Including related resources

    Example response with included resources. listing resource with included: author, author.profileImage and images relationships:

    {
      "data": {
        "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
        "type": "listing",
        "attributes": {
          "description": "7-speed Hybrid",
          "closed": false,
          "deleted": false,
          "geolocation": {
            "lat": 40.64542,
            "lng": -74.08508
          },
          "createdAt": "2018-03-23T08:40:24.443Z",
          "state": "published",
          "title": "Peugeot eT101",
          "publicData": {},
          "price": {
            "amount": 1590,
            "currency": "USD"
          }
        },
        "relationships": {
          "author": {
            "data": {"id": "3c073fae-6172-4e75-8b92-f560d58cd47c", "type": "user"}
          },
          "images": {
            "data": [
              {"id": "6a177221-247e-42a9-9cca-403238b86d7c", "type": "image"},
              {"id": "f8afadaa-dd4f-4536-b9a7-b405834dc25d", "type": "image"}
            ]
          }
        }
      },
      "included": [
        {
          "id": "3c073fae-6172-4e75-8b92-f560d58cd47c",
          "type": "user",
          "attributes": {
            "banned": false,
            "profile": {
              "displayName": "Joe D",
              "abbreviatedName": "JD",
              "bio": "Hello, I'm Joe."
            }
          },
          "relationships": {
            "profileImage": {
              "data": {"id": "a7c06f9d-5c69-4b70-adce-6f39639177b5", "type": "image"}
            }
          }
        },
        {
          "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"
              }
            }
          }
        },
        {
          "id": "a7c06f9d-5c69-4b70-adce-6f39639177b5",
          "type": "image",
          "attributes": {
            "variants": {
              "default": {
                "width": 720,
                "height": 540,
                "url": "https://www.example.com/image/a7c06f9d-5c69-4b70-adce-6f39639177b5"
              }
            }
          }
        }
      ]
    }
    

    Most resource types have relationships to other resources. When a given resource type has related resources, clients may request that the related resources be included in API responses for that given resource type.

    Including related resources is done by adding include query parameter to the API request. The value is a comma-separated list of relationships to include. For instance include=marketplace,author requests that the marketplace and author relationships be included in API responses that return a listing resource.

    When a relationship is included, the main resource(s) contain relationships objects and the overall response JSON object contains a top-level key included.

    The relationships object has keys corresponding to the requested relationships for the resource and the values have data The data is a resource reference (when the relationship is to single resource) or an array of resource references (when the relationship is to multiple resources).

    The value of included is an array with one or more included resource objects. All included resources are in that array and can be identified by their id and type.

    Including nested relationships (relationships of the related resources themselves - e.g. listing > author > marketplace) is generally not supported, unless explicitly documented for each resource type. For instance, requesting author.profileImage is supported for the listing resources. Supported nested relationships take the form of dot-separated names of relationships. In the example case of author.profileImage for a listing, the the author relationship of the listing and the profileImage relationship of the user, who is referred to by the author relationship are both present in the response (see the example response).

    Limiting number of included resources

    When a resource has a relationship that refers to multiple resources (e.g. listing's images), by default the API returns up to 100 of the related resources.

    API clients can limit included resources per relationship by using limit.RELATIONSHIP_NAME query parameter. E.g. use limit.images=2 to request only 2 images per listing in a /listings/query query. Multiple limit parameters may be used when multiple relationships need to be limited.

    For limiting the number of main resources returned by a read request, see Pagination.

    Sparse attributes

    Example request

    $ curl 'https://flex-api.sharetribe.com/v1/api/listings/show?id=c6ff7190-bdf7-47a0-8a2b-e3136e74334f&fields.listing=title,description&fields.author=profile.abbreviatedName' \
        -H 'Accept: application/json' \
        -H 'Authorization: bearer ACCESS_TOKEN'
    
    var listingId = new UUID("c6ff7190-bdf7-47a0-8a2b-e3136e74334f");
    sdk.ownListings.show({
      id: listingId,
      "fields.listing": ["title", "description"],
      "fields.author": ["profile.abbreviatedName"]
    }).then(res => {
      // res.data contains the response data
    });
    

    API clients can request that an endpoint returns only specific attributes in the response on a per-type basis by including a fields.RESOURCE_TYPE parameter.

    The value of the fields.RESOURCE_TYPE parameter is a comma-separated list that refers to the name(s) of the attributes to be returned. The field name can be nested. In this case, the nested path parts must be separated by a dot.

    If a client requests a restricted set of fields for a given resource type, an endpoint does not include additional fields in resource objects of that type in its response. If fields are not specified for a given resource type, a default set of resource fields is returned.

    Some resource types may have attributes that are not returned by the API by default. These attributes can be fetched only by explicitly specifing them in the fields.RESOURCE_TYPE parameter. For example, only a default variant for an image is returned by default.

    Pagination

    Example response for query /v1/api/listings/query?perPage=50,page=2

    {
      "data": [
        {
          "id": "c6ff7190-bdf7-47a0-8a2b-e3136e74334f",
          "type": "listing",
          "attributes": {
            "description": "7-speed Hybrid",
            "closed": false,
            "deleted": false,
            "geolocation": {
              "lat": 40.64542,
              "lng": -74.08508
            },
            "createdAt": "2018-03-23T08:40:24.443Z",
            "state": "published",
            "title": "Peugeot eT101",
            "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"
            }
          }
        },
        {...},
        {...}
      ],
      "meta": {
        "totalItems": 1014,
        "totalPages": 21,
        "page": 2,
        "perPage": 50
      }
    }
    

    Query API endpoints that return multiple resources (such as /listings/query) use pagination. The default page size is 100. Clients can request additional results or control page size with the following query parameters:

    Parameter Description
    page (positive integer) The page number.
    perPage (positive integer) Number of resources to return per page. Must be between 1 and 100.

    Paginated responses contain pagination information in the meta top-level response key. The following attributes are returned:

    Attribute Description
    totalItems Total number of resources that matched the query.
    totalPages Total number of pages, given the page size (perPage).
    page The number of the page returned in the response.
    perPage The number of resources returned per page. Affects the totalPages.

    Common query parameters

    The following list contains common query parameters that are supported by all or most API endpoints.

    Parameter Description
    include (string) Comma-separated list of relationships to be returned by the API. All API endpoints support this parameter.
    page (positive integer) Page number for read (also known as query) endpoints that return multiple resources.
    perPage (positive integer) Number of resources to be returned per page for read endpoints that return multiple resources.
    expand (boolean) Indicate whether the API write endpoint (also known as command) should return full resource (with attributes) or just a resource reference. Only applies to write API endpoints.
    fields.* (string) Comma-separated list of attributes for sparse attribute queries. All API endpoints support these parameters.
    limit.* (positive integer) Number of included resources to return per relationship. All API endpoints support these parameters.

    Marketplace

    API prefix

    /v1/api/marketplace/

    Example resource

    {
      "data": {
        "id": "16c6a4b8-88ee-429b-835a-6725206cd08c",
        "type": "marketplace",
        "number": 123,
        "bool": false,
        "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) 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,
          "createdAt": "2018-03-28T09:12:58.866Z",
          "profile": {
            "displayName": "Joe D",
            "abbreviatedName": "JD",
            "bio": "Hello, I'm Joe.",
            "publicData": {
              "age": 27
            }
          }
        }
      }
    }
    
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "user",
        attributes: {
          banned: false,
          createdAt: new Date("2018-03-28T09:12:58.866Z"),
          profile: {
            displayName: "Joe D",
            abbreviatedName: "JD",
            bio: "Hello, I'm Joe.",
            publicData: {
              age: 27
            }
          }
        }
      }
    }
    

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

    user resource format

    Attribute Description
    banned (boolean) Flag indicating whether the user is banned.
    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.

    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.

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

    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,
          "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"
            }
          }
        }
      }
    }
    
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: 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,
          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"
            }
          }
        }
      }
    }
    

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

    currentUser resource format

    Attribute Description
    banned (boolean) Flag indicating if the user is banned.
    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) Flag indicating if the user can accept payouts.
    stripeChargesEnabled (boolean) Flag indicating if charges can be created on behalf of the user.
    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.

    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.

    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,
          "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"
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: 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,
          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"
            }
          }
        }
      }
    }
    

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

    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,
          "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"
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: false,
          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"
            }
          }
        }
      }
    }
    

    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.

    Common errors

    HTTP status code Error code Description
    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,
          "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"
            }
          },
          "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,
          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"
            }
          },
          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. 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.
    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.

    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,
          "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"
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: false,
          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"
            }
          }
        }
      }
    }
    

    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.

    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,
          "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"
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: false,
          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"
            }
          }
        }
      }
    }
    

    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.

    Common errors

    HTTP status code Error code Description
    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,
          "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"
            }
          }
        }
      }
    }
    
    // res.data
    {
      data: {
        id: UUID {uuid: "3c073fae-6172-4e75-8b92-f560d58cd47c"},
        type: "currentUser",
        attributes: {
          banned: false,
          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"
            }
          }
        }
      }
    }
    

    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.

    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.verifyEmail().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.

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

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

    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.

    Common errors

    HTTP status code Error code Description
    409 email-not-found User with given email is not found in the marketplace.
    409 email-unverified User has not verified their email address. Password reset can not be done with unverified address.

    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.

    Common errors

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

    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",
          "publicData": {
            "address": {
              "city": "New York",
              "country": "USA",
              "state": "NY",
              "street": "230 Hamilton Ave"
            },
            "metadata": {
              "promoted": true
            },
            "category": "road",
            "gears": 22,
            "rules": "This is a nice, bike! Please, be careful with it."
          },
          "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",
          publicData: {
            address: {
              city: "New York",
              country: "USA",
              state: "NY",
              street: "230 Hamilton Ave"
            },
            metadata: {
              promoted: true
            },
            category: "road",
            gears: 22,
            rules: "This is a nice, bike! Please, be careful with it."
          },
          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).
    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 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 relationshipts: author.profileImage.
    images image many (optional) The ordered list of listing images, if any.

    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",
          "publicData": {
            "address": {
              "city": "New York",
              "country": "USA",
              "state": "NY",
              "street": "230 Hamilton Ave"
            },
            "metadata": {
              "promoted": true
            },
            "category": "road",
            "gears": 22,
            "rules": "This is a nice, bike! Please, be careful with it."
          },
          "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",
          publicData: {
            address: {
              city: "New York",
              country: "USA",
              state: "NY",
              street: "230 Hamilton Ave"
            },
            metadata: {
              promoted: true
            },
            category: "road",
            gears: 22,
            rules: "This is a nice, bike! Please, be careful with it."
          },
          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({lat: 40.0, lng: -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",
            "publicData": {
              "address": {
                "city": "New York",
                "country": "USA",
                "state": "NY",
                "street": "230 Hamilton Ave"
              },
              "metadata": {
                "promoted": true
              },
              "category": "road",
              "gears": 22,
              "rules": "This is a nice, bike! Please, be careful with it."
            },
            "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",
            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. Unless origin query parameter is given, results are sorted by listing createdAt time in descending order (i.e. newest listings are returned first).

    This query does not return listings that are in the closed state.

    Query parameters

    Parameter Description
    authorId (uuid) Match only listings belonging to given user ID.
    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.
    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 below for range syntax.
    pub_* Query listings by publicData attribute(s). See below.
    meta_* Query listings by metadata attribute(s). See below.

    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.

    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:

    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=VALUE1[,VALUE2[,...]] Match listings that have all given values for the given multi-enum ATTRIBUTE_KEY (i.e. AND semantics).
    long one pub_ATTRIBUTE_KEY=VALUE Match listings that have a value of ATTRIBUTE_KEY that is exactly equal toVALUE.
    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.

    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": 1
              }
            ]
          },
          "privateData": {
            "externalServiceId": "abcd-service-id-1234"
          },
          "publicData": {
            "address": {
              "city": "New York",
              "country": "USA",
              "state": "NY",
              "street": "230 Hamilton Ave"
            },
            "metadata": {
              "promoted": true
            },
            "category": "road",
            "gears": 22,
            "rules": "This is a nice, bike! Please, be careful with it."
          },
          "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: 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"}
        }
      }
    }
    

    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.

    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 day-based availability plan can be specified to indicate which days of the week are available or unavailable for booking. For explanation of how availability management works, see Listing availability management.

    Attribute Description
    type (string) Availability plan type. Currently, the only supported type is availability-plan/day for day-based availability management.
    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. Currently the only supported values for seats are 0 (day unavailable) or 1 and each booking always consumes 1 seat.

    If an 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.

    Listings without an availability plan are interpreted as having 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.

    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.

    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": 1
              },
              {
                "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: 1
              },
              {
                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).

    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": 1
          },
          {
            "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"
      },
      "images": [
        "6a177221-247e-42a9-9cca-403238b86d7c",
        "f8afadaa-dd4f-4536-b9a7-b405834dc25d"
      ]
    }'
    
    sdk.ownListings.create({
      title: "Peugeot eT101",
      description: "7-speed Hybrid",
      geolocation: new LatLng({lat: 40.64542, lng: -74.08508}),
      availabilityPlan: {
        type: "availability-plan/day",
        entries: [
          {
            dayOfWeek: "mon",
            seats: 1
          },
          {
            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: new Money({amount: 1590, currency: "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": 1
              },
              {
                "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"
          }
        },
        "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: 1
              },
              {
                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"}
        },
        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.

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

    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."
      },
      "metadata": {
        "promoted": true
      },
      "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({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."
      },
      metadata: {
        promoted: true
      },
      price: new Money({amount: 1590, currency: "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": {
            "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"}
            ]
          }
        }
      },
      "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: {
            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"}
            ]
          }
        }
      },
      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.

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

    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 1000 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. Pass null to remove the availability plan from the listing.
    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.

    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.

    Body parameters

    Parameter Description
    id (uuid) The listing ID.

    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.

    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.

    Body parameters

    Parameter Description
    id (uuid) The listing ID.

    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.

    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.

    availabilityException resource format

    Attribute Description
    seats (number) An integer number of available seats for the exception. Currently the only supported values for seats are 0 (day unavailable) or 1.
    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.

    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 (string, timestamp) The start date and time for the query range in ISO 8601 format. The start time must be between one day in the past and 365 days in the future.
    end (string, 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 365 days in the future or at most 90 days from the start time (whichever comes sooner).

    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: 1
    }, {
      expand: true
    }).then(res => {
      // res.data
    });
    

    Example response shell { "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" } } }

    // 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")
        }
      }
    }
    

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

    Body parameters

    Parameter Description
    seats (number) Integer number of available seats. Currently the only supported values for seats are 0 or 1.
    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.

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

    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.

    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.

    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.

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

    Variant Transformation Width Height
    default fit, clip 750px 750px
    landscape-crop fit, crop 400px 267px
    landscape-crop2x fit, crop 800px 533px
    landscape-crop4x fit, crop 1600px 1066px
    landscape-crop6x fit, crop 2400px 1602px
    scaled-small fit, clip 320px 320px
    scaled-medium fit, clip 750px 750px
    scaled-large fit, clip 1024px 1024px
    scaled-xlarge fit, clip 2400px 2400px
    square-small fit, crop 240px 240px
    square-small2x fit, crop 480px 480px
    facebook fit, crop 1200px 630px
    twitter fit, crop 600px 314px
    Transformation Description
    fit, clip 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.
    fit, 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 10MB.

    Multipart body parameters

    Parameter Description
    image The image content.

    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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "currency": "USD"
              },
              "includeFor": [
                "provider"
              ]
            }
          ],
          "protectedData": {
            "phoneNumber": "+1-202-555-5555"
          },
          "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                currency: "USD"
              },
              includeFor: [
                "provider"
              ]
            }
          ],
          protectedData: {
            phoneNumber: "+1-202-555-5555"
          },
          transitions: [
            {
              transition: "transition/request",
              createdAt: new Date("2018-03-27T12:30:03.100Z"),
              by: "customer"
            }
          ]
        }
      }
    }
    

    The transaction API resource type represents information about transactions.

    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, timestamp) The name of the last transition that happened in the transaction. See Transaction engine.
    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 number of units that the line item represents. Can be non-integer or negative number.
    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.
    transitions (array) The transaction's transition history - list of transition objects, in chronological order.
    transitions.*.transition (string) The name of the transition. See Transaction engine.
    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/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.

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

    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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                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": 3180,
              "currency": "USD"
            },
            "payoutTotal": {
              "amount": 2862,
              "currency": "USD"
            },
            "lineItems": [
              {
                "code": "line-item/day",
                "quantity": 2,
                "reversal": false,
                "unitPrice": {
                  "amount": 1590,
                  "currency": "USD"
                },
                "lineTotal": {
                  "amount": 3180,
                  "currency": "USD"
                },
                "includeFor": [
                  "customer",
                  "provider"
                ]
              },
              {
                "code": "line-item/provider-commission",
                "percentage": -10.0,
                "reversal": false,
                "unitPrice": {
                  "amount": 3180,
                  "currency": "USD"
                },
                "lineTotal": {
                  "amount": -318,
                  "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: 3180,
              currency: "USD"
            },
            payoutTotal: {
              amount: 2862,
              currency: "USD"
            },
            lineItems: [
              {
                code: "line-item/day",
                quantity: 2,
                reversal: false,
                unitPrice: {
                  amount: 1590,
                  currency: "USD"
                },
                lineTotal: {
                  amount: 3180,
                  currency: "USD"
                },
                includeFor: [
                  "customer",
                  "provider"
                ]
              },
              {
                code: "line-item/provider-commission",
                percentage: -10.0,
                reversal: false,
                unitPrice: {
                  amount: 3180,
                  currency: "USD"
                },
                lineTotal: {
                  amount: -318,
                  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
    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.
    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.

    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",
        "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"),
        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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                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.

    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-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-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' \
        -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",
        "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"),
        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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                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.

    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-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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                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.

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

    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": 3180,
            "currency": "USD"
          },
          "payoutTotal": {
            "amount": 2862,
            "currency": "USD"
          },
          "lineItems": [
            {
              "code": "line-item/day",
              "quantity": 2,
              "reversal": false,
              "unitPrice": {
                "amount": 1590,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": 3180,
                "currency": "USD"
              },
              "includeFor": [
                "customer",
                "provider"
              ]
            },
            {
              "code": "line-item/provider-commission",
              "percentage": -10.0,
              "reversal": false,
              "unitPrice": {
                "amount": 3180,
                "currency": "USD"
              },
              "lineTotal": {
                "amount": -318,
                "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: 3180,
            currency: "USD"
          },
          payoutTotal: {
            amount: 2862,
            currency: "USD"
          },
          lineItems: [
            {
              code: "line-item/day",
              quantity: 2,
              reversal: false,
              unitPrice: {
                amount: 1590,
                currency: "USD"
              },
              lineTotal: {
                amount: 3180,
                currency: "USD"
              },
              includeFor: [
                "customer",
                "provider"
              ]
            },
            {
              code: "line-item/provider-commission",
              percentage: -10.0,
              reversal: false,
              unitPrice: {
                amount: 3180,
                currency: "USD"
              },
              lineTotal: {
                amount: -318,
                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.

    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

    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.

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

    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.

    processTransition resource format

    Attribute Description
    name (string) The uniquely identifying name of the transition
    author (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 engine.
    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, object.
    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": {
          "start": "2018-04-20T00:00:00.000Z",
          "end": "2018-04-22T00:00:00.000Z",
          "state": "accepted"
        }
      }
    }
    
    {
      data: {
        id: UUID {uuid: "5a3e765a-06ea-4ca6-ba7f-f394ad2888a1"},
        type: "booking",
        attributes: {
          start: new Date("2018-04-20T00:00:00.000Z"),
          end: new Date("2018-04-22T00:00:00.000Z"),
          state: "accepted"
        }
      }
    }
    

    The booking resource type represents information about a booking.

    booking resource format

    Attribute Description
    start (string, timestamp) The date and time the booking starts.
    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.
    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.

    booking states

    State Description
    pending A new booking that has been requested by a customer.
    accepted A booking that has been accepted by the provider.
    declined A booking that has been declined by the provider.
    cancelled A booking that has been cancelled.

    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.

    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": {
            "start": "2018-04-20T00:00:00.000Z",
            "end": "2018-04-22T00: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: {
            start: new Date("2018-04-20T00:00:00.000Z")
            end: new Date("2018-04-22T00:00:00.000Z")
            state: "accepted"
          }
        },
        {...},
        {...}
      ],
      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 (string, timestamp) The start date and time for the query range in ISO 8601 format. The start time must be between one day in the past and 180 days in the future.
    end (string, 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 180 days in the future or at most 90 days from the start time (whichever comes sooner).
    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

    {
      "data": {
        "id": "d479cd2d-5890-405a-b895-20a9a1ffdde7",
        "type": "timeSlot",
        "attributes": {
          "type": "time-slot/day",
          "start": "2018-04-22T00:00:00.000Z",
          "end": "2018-04-23T00:00:00.000Z"
        }
      }
    }
    
    {
      data: {
        id: UUID {uuid: "d479cd2d-5890-405a-b895-20a9a1ffdde7"},
        type: "timeSlot",
        attributes: {
          type: "time-slot/day",
          start: new Date("2018-04-22T00:00:00.000Z"),
          end: new Date("2018-04-23T00:00: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, you can only create bookings that span over continuous available time slots.

    timeSlot resource format

    Attribute Description
    type (string) The type of the slot. At present, the only supported type is time-slot/day
    start (string, timestamp) The date and time the time slot starts.
    end (string, timestamp) The date and time the time slot ends. 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.

    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",
            "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",
            "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",
            "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",
            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",
            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",
            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. The start time must be between one day in the past and 180 days in the future.
    end (timestamp) End time of the interval to query for (exclusive). The end time must be after that start time and must be at most 180 days in the future or at most 90 days from the start time (whichever comes sooner).

    At present, only queries for time slots of type time-slot/day are supported. The start and end timestamps are interpreted as dates (i.e. the time component is ignored).

    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"
        }
      }
    }
    
    {
      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")
        }
      }
    }
    

    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.

    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.

    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.

    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.