Improved Documentation

[kvindascr]

Hello Guys,

Thanks a lot for the great effort on this module.

I'm currently implementing an ecom in WooCommerce/Gatsby and found the wp-graphql project which is great.

But while trying to use it, in specific the WooCommerce project I have been pretty much guessing how I'm suppose to use it.

At the moment seems that I have understood well, but I have seen that documentation is definitely lacking.

I'm no PHP programmer, but wanted to offer a hand on improving documentation if that might work.

[kidunot89]

@kvindasAB I recommend using WPGraphiQL or some GraphQL client with the ability to view the schema. You can both build and test you queries in the client and transfer them to your project once you have confirmed that they are working.

[kvindascr]

Hello @kidunot89 I have been doing that with GraphiQL and while I understand exactly from the schema, how to call a mutation or what attributes can be queried, I'm still missing documentation on how I am supposed to use different mutations and or queries.

I'm not an expert on how WooCommerce works underneath, and maybe that's why I might feel a bit lost, but I do think there is a high chance other people is my shoes.

As an example, the schema has a cart query object, which reflects the user current cart, and while this might be obvious for the developer who developed the schema, it was not obvious to me.

Same happens with customer.

And also it is not obvious for a simple case scenario, if I needed to use either checkout mutation or createOrder (maybe I'm not recalling the exact name).

But I think you get my point.

Some guides or redirections are needed, not for the detail on how to call a mutation, but to understand what the mutation exactly does in the backend, and how to implement specific functionality flows.

Let me know your thoughts.

[kidunot89]

@kvindasAB I'm sorry for the lack of documentation. I've got a doc site in the works. It's been a slow going process, but that because the documentation consists of a implementation tutorials for React/Apollo (Sorry, that's the stack what I'm most familiar with) and tips on usage with different UI implementation. This maybe along the lines of what you're looking for. Until it's complete, you may be able to find some noteworthy info from the devs in the WPGraphQL slack. I know a few of them have created pretty impressive applications.

[kvindascr]

@kidunot89 as indicated in my original post, I would like to also offer my help to improve the documentation, again if its something that might work.

In any case, let me know

[trevorblades]

@kidunot89 I'm very familiar with React/Apollo and I'd be happy to help create examples!

At the moment, I'm having a hard time understanding how I should be implementing checkout. How should I collect credit card info? If I'm using Stripe as a payment gateway, I could imagine obtaining a "token" on the frontend using Stripe Elements. However I'm unsure how to pass this information back to Woocommerce to complete the checkout process. Any pointers would be much appreciated!

Thank you for your work on this project 🙏

[kidunot89]

@trevorblades There are multiple ways to process user order.

Managing User session

1. Add an item to the cart using addToCart.
2. Retrieve session token from initial addToCart mutation and store for reuse in queries use Apollo middleware/afterware layers.
3. Add/remove items to cart mutations addToCart, updateItemQuantities, etc...
4. (Optional) Set shipping rates with updateShippingMethod mutation.

Checking Out ~ this is typical done after the submit button is clicked on the checkout page

There are current two ways of processing your order.

Method 1 - (recommended)

1. Create user payment token and process order payment using a Client-side JS library like Stripe.js to retrieve a transactionId.
2. After the payment as been successful processed, create the order using the createOrder or checkout(recommend) mutation. Be sure to set the transactionId and isPaid: true on the CreateOrderInput or CheckoutInput types respective to whatever mutation your using.

Method 2

1. Create order using the createOrder or checkout mutation.
2. Use the redirect url provided in the mutation output provided by the payment gateway to redirect or open a new window to a payment page

[kidunot89]

@trevorblades @kvindasAB I would also recommend viewing the PR summary notes for releases. I put a lot of examples/documentation in the PR summaries. Be sure to click on the links to the sub-PRs. I break release PRs into smaller PRs and those PRs have the examples and documentation.

• Release v0.1.0 - Cart mutations
• Release v0.1.2 - Cart Session Handling
• Release v0.2.0 - Order/Checkout mutations
• Release v0.2.1 - New Product connection filters and checkout mutation bugfixes
• Release v0.2.2
• Release v0.3.0
• Release v0.3.1
• Release v0.3.2
• Release v0.3.3
• Release v0.4.0
• Release v0.4.1

[trevorblades]

@kidunot89 thank you so much for the detailed explaination and PR links! transactionId is exactly what I was missing.

[kvindascr]

@kidunot89 Why don't start by creating a small documentation, maybe in something as simple as a markdown, with the information you posted in this comments.

I can help creating a first version of it, and you can of course review it in a pull request, but again, I think this is very basic information the project is missing.

Let me know if this is something you would find interesting.

[kidunot89]

@trevorblades Please note that currently transactionId and isPaid don't exist on the checkout mutation. This PR will remedy that.

@kvindasAB I will once I have something to put up.

[kidunot89]

@trevorblades See this
If should shine more light on your issue.

[trevorblades]

Thanks @kidunot89!

[kidunot89]

@kvindasAB I've added the docs to the repo. It's hosted here.
It needs a lot of work, I'll accept any help you can provide.